The standalone compiler: `ohuac`¶

The ohuac executable is a standalone program which can compile a source file written in one of the ohua Frontends for ohua algorithms and generate code for various platforms.

Getting it¶

Prebuilt binaries are available for 64bit Linux and OSX. Provided for each release by Travis CI.

Simply download the appropriate executable for you platform (ohuac-linux or ohuac-osx) from the releases page.

Building from source / Getting the source code¶

The source code for the compiler can be found on GitHub. However major parts of the compiler are separate libraries. For more information on the repository structure see the project organisation page.

ohuac is written in Haskell and uses the stack tool for building and dependency management. If you have stack installed already you can simply download the source from the releases page and run stack install.

This downloads and builds all dependencies, as well as the Haskell compiler ghc, should it not be present already. It should not interfere with any system-level libraries, Haskell ecosystems etc.

It builds the executable ohuac and copies it to ~/.local/bin. If you do not wish this use stack build instead and find the path of the finished binary using stack exec -- which ohuac afterwards. After building the binary can be freely moved to any location on the system.

Usage¶

The capabilities and options for the compiler can be interactively explored by calling ohuac --help or ohuac COMMAND --help to get help for a specific COMMAND.

The `build` command¶

The most common command is build.

The build command transitively builds your ohua modules. This means it not only compiles the one module you directly specify but also all modules it may depend on.

Currently the search path for modules cannot be influenced. Therefore they must be in a specific location, which is module/submodule.ohuac. The type of file (.ohuac or .ohuas) does not matter in this case. In fact they can also be mixed. A ohuas file can import a module that is defined as a ohuac file.

As an example we may have a module A.ohuac, which depends on foo.bar.B and foo.C.

A
|-- foo.bar.B
'-- foo.C

During compilation the compiler will look for these dependencies at foo/bar/B.ohuac or foo/bar/B.ohuas and foo/C.ohuac or foo/C.ohuas. All paths being relative to the current working directory. So if the compiler was called with ohuac build A.ohuac, the working directory is expected to look something like this

WORKING_DIR/
     |-- A.ohuac
     '-- foo/
          |--bar/
          |   '-- B.ohuac
          '-- C.ohuas

If both an .ohuac and .ohuas file is found for a particular dependency the compiler will exit with an error.

Universal options¶

The options listed in ohuac --help apply to all subcommands. They are generally prepended to the options passed to the subcommand.

Supported targets for code generation¶

The standalone compiler currently supports two compilation targets. One is a universal format, which simply encodes the dataflow graph directly in JSON and a second which creates a java class.

JSON Graph repesentation¶

The JSON output from ohua is selected with the -g json-graph option. The default file extension is .ohuao.

This representation only encodes the dataflow graph and the stateful functions used. It is intended to be a universal, easily to use intermediate for backeds which have no direct support in ohuac yet. Such a backend only has to define the runtime for the dataflow execution and the loading and linking of stateful functions, ohuac will take care of parsing, interpreting and optimising the algorithms.

A simple runnable java class¶

The -g simple-java-class code gen option is a very lightweight code generation for the java platform.

It generates a class where the module path is its package and the algorithm name is the name of the class. E.g. namespace foo.bar.baz with the main algorithm selected generates a class foo.bar.baz.Main.

For an algorithm main with arguments A, B, C and return type of D, the class has the following structure

class Main {
   public static C invoke(A argument0, B argument1, C argument2);
   public static Configured configure(RuntimeProcessConfiguration configuration);

   public static class Configured {
       public Prepared prepare(A argument0, B argument1, C argument2);
   }
   public static class Prepared {
       public static D invoke();
   }
}

The argument and return types default to Object.

The structure of the class follows a simple schema. Each algorithm class has two static methods invoke and configure. invoke simply executes the algorithm with the default runtime parameters. configure allows customization of runtime parameters.

Furthermore there are always two inner classes, Configured and Prepared. The two inner classes represent stages of algorithm configuration. Configured is a graph with an associated runtime configuration and can be turned into a Prepared by calling prepare with the arguments specified in the algorithm description.

The standalone compiler: ohuac¶