The Ivory toolchain is made up of 4 packages found in the Ivory repository:
The Ivory language is defined in the ivory package. Users should only use the Ivory API exported by the Ivory.Language module.
Ivory’s Module type is the unit of compilation. There are no tools for user introspection of a Module value.
The Ivory C-language compiler is defined in the ivory-backend-c package.
Most users will want to use the compile function from the Ivory.Compile.C.CmdlineFrontend module. compile has type [Module] -> IO (): it takes a collection of Ivory modules and writes the compiled C sources to the disk according to command line options (i.e. System.Environment.getArg).
If you are building the Ivory compiler into some other sort of Haskell application, lower level primitives are exported by the Ivory.Compile.C module.
The compileWith function from the Ivory.Compile.C.CmdlineFrontend module extends compile with two additional optional arguments, a SizeMap (defined by Ivory.Opts.CFG) which may aid in static analysis passes, and a [IO FilePath] which specifies the search path for additional C source dependencies.
Some Ivory libraries require external definitions given by C source files. Such a library should give a SearchDir module exporting a value searchDir :: IO FilePath.
For example, the commonly used ivory-hw package requires a C header, which is installed as a cabal data-file. The directory to find the installed support file is given by searchDir in the module Ivory.HW.SearchDir.
The command line arguments expected by Ivory.Compile.C.CmdlineFrontend.compile can be found by running a compile program with the –help flag.
Support for verifying user- and compiler- inserted assertions in Ivory programs is provided by the ivory-model-check package.
Ivory optimization passes are implemented in the ivory-opts package.
Optimization passes are used by default by the Ivory.Compile.C.CmdlineFrontend.compile compiler. Command line flags are available to disable passes individually.
One of the downsides of embedded DSLs like Ivory is that tools like the above generally do not have access to the original source information for error reporting. To address this issue, we have implemented a plugin for GHC (>= 7.8) that adds references to the original Haskell source in the Ivory code. The granularity is only at the level of individual Ivory statements, but nonetheless very helpful in discovering the source of an error.
The source location plugin can be enabled by compiling your Ivory program with -fplugin=Ivory.Language.Plugin. You also need to tell GHC to retain the source locations for our plugin to see, which can be done in three ways:
-fhpc,-prof (and preferably -fprof-auto-calls for maximum granularity), or