developing.md

Developers' documentation

Table of Contents

• Developers' documentation
  • Upstream documentation
  • 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

C++ implementation:

• Parser:
  • Release 4.0
  • Release 5.0
  • Release 6.0
• Record codes:
  • Bitstream format:
    • Release 4.0
    • Release 5.0
    • Release 6.0
  • LLVM bitcode:
    • Release 4.0
    • Release 5.0
    • Release 6.0

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.

Travis CI build

Note: the CI build doesn't run the full test suite, just some regression tests and the unit tests.

The .travis.yml file is generated using haskell-ci. However, we add the following:

  - git clone https://github.com/elliottt/llvm-pretty llvm-pretty
  - "printf 'packages: \".\" llvm-pretty/\\n' > cabal.project"

and:

  - git clone https://github.com/elliottt/llvm-pretty llvm-pretty
  - "printf 'packages: llvm-pretty-bc-parser-*/*.cabal llvm-pretty/*.cabal\\n' > cabal.project"

so that it picks up the latest llvm-pretty.

When Cabal supports fetching tarballs, we can use the following so that it fetches the latest llvm-pretty from Github.

  - "printf 'packages: llvm-pretty-bc-parser-*/*.cabal https://github.com/elliottt/llvm-pretty/archive/master.tar.gz \\n' > cabal.project"