Skip to content

Latest commit

 

History

History
86 lines (60 loc) · 3.12 KB

DEVELOPER.rst

File metadata and controls

86 lines (60 loc) · 3.12 KB
Raw

DDL Developer Notes

This documentation is focused on developers writing daedalus specified parsers (.ddl files).

General Structure

Note the general structure of the multiple cabal packages here:

  • pdf-cos - a library providing low-level pdf parsing, but the idea is that we keep demo related stuff out of it. It is a Haskell library, but some of the Haskell modules are generated by using daedalus.

  • pdf-driver is a package that builds executables (pdf-hs-driver, pdf-dom) that use the pdf-cos library. They also use daedalus to generate some Haskell modules, and these specifications need to refer to some of definitions in pdf-cos/spec/. To typecheck these specs, we need the definitions (well, actually just their types, really) of the specs in pdf-cos, but we should not compile them again, as if we did we'd end up with two copies of the code and a big confusion.

    • Previously we used 'sym-links' in pdf-driver/spec/ to refer to the modules in pdf-cos/spec/ that are needed to type-check the specs before compiling to Haskell code. One should really think of them as interface files rather than full modules. However, ...

    • Currently, to avoid the confusion that symlinks have sometimes caused, we now handle this in pdf-driver by invoking daedalus with two module search paths (this is handled in pdf-driver/Setup.hs):

      [ "spec"             -- new ddl modules in this directory
, "../pdf-cos/spec"  -- 'library' ddl modules here
]

Adding Your Modules

Guide to adding new daedalus modules:

  • If you have a generic, re-usable .ddl module, New.ddl
    • Put the ddl here: pdf-cos/spec/New.ddl
    • Add the module name "New" to the mods list in pdf-cos/Setup.hs. (CAVEAT: if New.ddl isn't compilable by daedalus this will break the rest of the build.)
  • If you have a new pdf tool, it probably belongs in pdf-driver/, and if there are ddl modules that are tool specific, put them in pdf-driver/spec/.
    • add the module name "New" to the mods list in pdf-driver/Setup.hs (CAVEAT: as before, if the New.ddl isn't compilable by daedalus, this will break the rest of the build.)
  • And in either case, remember to update the respective cabal files:
    • add the path to the ddl file to extra-source-files:
    • add the basename/module-name to both exposed-modules and autogen-modules

Debugging

Note this communication from Iavor (on 2021-05-03):

You can do debug tracing like this:

place this declaration in a file called Debug.ddl
def Trace (x : [uint 8]) : {}
import the Debug module and use Trace, for example like this:
import Debug

def Main = block
  Match "a"
  Trace "hello"
  Match "b"
The Trace will output the offset in the file and the message you gave it

Thus, in pdf-cos/spec we have a Debug.ddl module which has Trace. It is defined (as {}) but when you use it, you will see trace messages when you invoke your parser.