developing.md

Developers' documentation

Table of Contents

• Developers' documentation
  • Upstream documentation
  • Building
  • Running the tests
    • llvm-disasm-test
      • description
      • use
    • regression-test
    • unit-test
  • Travis CI build

Upstream documentation

Official (yet incomplete) reference: https://llvm.org/docs/BitCodeFormat.html

Relevant parts of the upstream C++ implementation:

• Parser (14.x)
• Record codes:
  • Bitstream enum values (14.x)
  • LLVM bitcode enum values (14.x)

Building

Make sure you have cloned the llvm-pretty submodule before building:

$ 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:

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,

./dist/build/disasm-test/disasm-test --help

If you have Nix installed, you can easily compare against multiple versions of llvm-dis, e.g.

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.

fuzzing

See the README in that directory.

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
• The Cabal file's Tested-with field
• The Nix flake
• CI workflows