# Developers' documentation
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
- [Developers' documentation](#developers-documentation)
- [Upstream documentation](#upstream-documentation)
- [Building](#building)
- [Running the tests](#running-the-tests)
- [`llvm-disasm-test`](#llvm-disasm-test)
- [description](#description)
- [use](#use)
- [`regression-test`](#regression-test)
- [`unit-test`](#unit-test)
- [Travis CI build](#travis-ci-build)
<!-- markdown-toc end -->
## Upstream documentation
Official (yet incomplete) reference: https://llvm.org/docs/BitCodeFormat.html
Relevant parts of the upstream C++ implementation:
+ [Parser (14.x)](https://github.com/llvm/llvm-project/blob/release/14.x/llvm/lib/Bitcode/Reader/BitcodeReader.cpp)
+ Record codes:
* [Bitstream enum values (14.x)](https://github.com/llvm/llvm-project/blob/release/14.x/llvm/include/llvm/Bitstream/BitCodes.h)
* [LLVM bitcode enum values (14.x)](https://github.com/llvm/llvm-project/blob/release/14.x/llvm/include/llvm/Bitcode/LLVMBitCodes.h)
## Building
Make sure you have cloned the `llvm-pretty` submodule before building:
```bash
$ git submodule update --init
$ cabal build
```
## Running the tests
### `llvm-disasm-test`
#### description
This test compares the behavior of `llvm-disasm` against that of `llvm-dis`, by
having them both disassemble the same file and diffing their output (in general,
we don't expect them to exactly match).
Additionally, by default this test does a "round-trip" comparison of
`llvm-disasm` against itself. After disassembling the first time, it reassembles
the output of `llvm-disasm` and runs it again. It then compares both the
ASTs and the LLVM assembly generated by the first and second run of
`llvm-disasm`, to ensure that the printer/parser combo is idempotent.
#### use
To compare the behavior of `llvm-disasm` against that of `llvm-dis`:
```bash
cabal build
./dist/build/disasm-test/disasm-test ./disasm-test/tests/fun-attrs.ll
# When using cabal new-build, the binary locations aren't so nice.
$(find . -name disasm-test -type f) disasm-test/tests/*.ll
```
To see all the options,
```bash
./dist/build/disasm-test/disasm-test --help
```
If you have [Nix](https://nixos.org/nix/) installed, you can easily compare
against multiple versions of `llvm-dis`, e.g.
```bash
nix-shell --pure -p llvm_6 --run "./dist/build/disasm-test/disasm-test ./disasm-test/tests/fun-attrs.ll"
```
### `regression-test`
See [the README in that directory](../regression-test/README.md).
### `fuzzing`
See [the README in that directory](../fuzzing/README.md).
### `unit-test`
These are run with `cabal test` or `cabal new-test`.
## Supported GHC Versions
A policy on which GHC versions to support must balance the benefits of wide
applicability/support against the drawbacks of additional costs of development,
including developer time and CI budgets. Our policy is to support three versions
of GHC at a time. We try to support new versions of GHC as soon as they are
supported by all of libraries that llvm-pretty-bc-parser depends on.
When updating the supported GHC versions, remember to update:
- [The README](../README.md)
- [The Cabal file](../llvm-pretty-bc-parser.cabal)'s `Tested-with` field
- [The Nix flake](../flake.nix)
- [CI workflows](../.github/workflows)