SYNOPSIS

jhc [OPTION ..] Main.hs -o main

Using

Building Projects

Jhc does its own dependency chasing to track down source files, you need only provide it with the file containing your 'main' function on the command line. For instance, if you had a program 'HelloWorld.hs', the following would compile it to an executable named 'hello'.

; jhc HelloWorld.hs -o hello

Jhc searches for modules in its search path, which defaults to the current directory. Modules are searched for based on their names. For instance, the module Data.Foo will be searched for in 'Data/Foo.hs' and 'Data.Foo.hs'. The search path may be modifed with the '-i' command line option, or by setting the 'JHC_PATH' environment variable.

Using Libraries

jhc libraries are distributed as files with an 'hl' suffix, such as 'base-1.0.hl'. In order to use a haskell library you simply need to place the file in a directory that jhc will search for it. For instance, $HOME/lib/jhc. You may set the environment variable JHC_LIBRARY_PATH to specify alternate locations to search for libraries or specify directory to search with the -L command line option. -L- will clear the search path.

You can then use libraries with the '-p' command line option, for instance if you had a library 'mylibrary-1.0.hl' in your search path, the following would use it.

; jhc -p mylibrary MyProgram.hs -o myprogram

You can list all available libraries by passing the --list-libraries option to jhc. If you include '-v' for verbose output, you will get detailed information about the libraries in a YAML format suitable for processing by external tools.

Environment Variables

Jhc's behavior is modified by several enviornment variables.

JHC_OPTS : this is read and appended to the command line of jhc invocations.

JHC_PATH : This specifies the path to search for modules.

JHC_LIBRARY_PATH : This specifies the path to search for libraries.

JHC_CACHE : This specified the directory jhc will use to cache values. having a valid cache is essential for jhc performance. It defaults to ~/.jhc/cache.

Building Haskell Libraries

Libraries are built by passing jhc a file describing the library via the --build-hl option. The library file format is a stadard YAML file.

; jhc --build-hl mylibrary.yaml

Library File Format

The library file is a YAML document, jhc will recognize several fields and ignore unknown ones.

Name : The name of your library

Version : The version of your library, The version number is used to differentiate different versions of the library passed to the '-p' command line option but is not otherwise special to jhc.

Exposed-Modules : A list of modules to be included in the library and exposed to users of the library as its public interface. This may include modules that are part of another library, they will be re-exported by the current library.

Hidden-Modules : A list of modules that the library may use internally but that should not be exposed to the user. Jhc may optimize based on this information. If this list is not exhaustive jhc will still build your library, but it will print out a warning.

Extensions : A list of extensions which should be enabled during compilation of this module. When possible, jhc will match ghc extensions to their closest jhc counterparts.

Options : Extra command line options to jhc for this library build.

Build-Depends : libraries to include, in the same format as passed to the '-p' command line option

Hs-Source-Dirs : Directory to search for Haskell source files in, this differs from the '-i' command line option in that the directory in this field is relative to the directory the library description .yaml file is located while the '-i' option is always relative to the current working directory.

Include-Dirs : directories to be included in the preprocessor search path as if via '-I'. The directories are interpreted relative to the directory that contains the yaml file.

C-Sources : C files that should be linked into programs that utilize this library.

Include-Sources : files that should be made available for inclusion when compiling the generated C code but don't need to be linked into the executable.

example library files can be seen in lib/jhc/jhc.yaml and lib/base/base.yaml

Dependency Information

Jhc can output dependency information describing how source files and libraries depend on each other while compiling code. The dependency information is generated when the --deps name.yaml option is passed to jhc. It is presented in the standard YAML format and its fields are as described below.

• LibraryDeps: the libraries that are dependend on. It is a hash of library ids to the specific filename of the library used.
• LibraryDesc: if building a library, this field contains the name of the library description file used.
• ModuleDeps: a hash of module names to the list of modules that are directly dependend on by said module.
• ModuleSouce: a hash of module name to the haskell source file used.

An example tool to processs the deps.yaml file and spit out appropriate Makefile rules is included as 'utils/deps_to_make.prl'.

Options

Usage: jhc [OPTION...] Main.hs
  -V                --version                 print version info and exit
                    --version-context         print version context info and exit
                    --help                    print help information and exit
                    --info                    show compiler configuration information and exit
                    --purge-cache             clean out jhc compilation cache
  -v                --verbose                 chatty output on stderr
  -z                                          Increase verbosity of statistics
  -d [no-]flag                                dump specified data during compilation
  -f [no-]flag                                set or clear compilation options
  -X ExtensionName                            enable the given language extension
  -o FILE           --output=FILE             output to FILE
  -i DIR            --include=DIR             where to look for source files
  -I DIR                                      add to preprocessor include path
  -D NAME=VALUE                               add new definitions to set in preprocessor
                    --optc=option             extra options to pass to c compiler
  -c                                          just compile the modules, caching the results.
  -C                                          compile to C code
  -E                                          preprocess the input and print result to stdout
  -k                --keepgoing               keep going on errors
                    --cross                   enable cross-compilation, choose target with the -m flag
                    --stop=parse/typecheck/c  stop after the given pass, parse/typecheck/c
                    --width=COLUMNS           width of screen for debugging output
                    --main=Main.main          main entry point
  -m arch           --arch=arch               target architecture options
                    --entry=<expr>            main entry point, showable expression
                    --show-ho=file.ho         Show ho file
                    --noauto                  Don't automatically load base and haskell98 packages
  -p package                                  Load given haskell library package
  -L path                                     Look for haskell libraries in the given directory
                    --build-hl=desc.yaml      Build hakell library from given library description file
                    --annotate-source=<dir>   Write preprocessed and annotated source code to the directory specified
                    --deps=<file.yaml>        Write dependency information to file specified
                    --interactive             run interactivly                                                             ( for debugging only)
                    --ignore-cache            Ignore existing compilation cache entries.
                    --readonly-cache          Do not write new information to the compilation cache.
                    --no-cache                Do not use or update the cache.
                    --cache-dir=JHC_CACHE     Use a global cache located in the directory passed as an argument.
                    --stale=Module            Treat these modules as stale, even if they exist in the cache
                    --list-libraries          List of installed libraries
                    --tdir=dir/               specify the directory where all intermediate files/dumps will be placed.
valid -d arguments: 'help' for more info
    all-types, aspats, atom, bindgroups, boxy-steps, c, class, class-summary, core, core-afterlift
    core-beforelift, core-initial, core-mangled, core-mini, core-pass, core-steps, datatable
    datatable-builtin, dcons, decls, defs, derived, e-alias, e-info, e-size, e-verbose, exports, grin
    grin-datalog, grin-final, grin-graph, grin-initial, grin-normalized, grin-posteval, grin-preeval
    imports, ini, instance, kind, kind-steps, optimization-stats, parsed, preprocessed, program
    progress, renamed, rules, rules-spec, scc-modules, sigenv, srcsigs, stats, steps, tags, the
    types, verbose, veryverbose
valid -f arguments: 'help' for more info
    bang-patterns, boehm, controlled, cpp, debug, default, defaulting, exists, ffi, forall, full-int
    glasgow-exts, global-optimize, inline-pragmas, jgc, lint, m4, monomorphism-restriction, negate
    prelude, profile, raw, rules, standalone, type-analysis, type-families, unboxed-tuples
    unboxed-values, user-kinds, wrapper

Code Options

Various options affecting how jhc interprets and compiles code can be controlled with the '-f' flag, the following options are availible, you can negate any particular one by prepending 'no-' to it.

Dumping Debugging Information

You can have jhc print out a variety of things while running as Controlled by the '-d' flag. The following is a list of possible parameters you can pass to '-d'.

AUTHORS