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'. As an extension, jhc will also search for '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

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 file format is a simplified version of the cabal format. The name of the generated file will be basename-version.hl.

; jhc --build-hl mylibrary.cabal

Name: The Name of your library
Version: The Version of your library
Exposed-Modules: Comma Seperated list of modules to be included in the library and made availabe to users of the library
Hidden-Modules: Comma Seperated list of modules that will be used by the library internally, but not be made available outside 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'.

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.

Function Properties

These must appear in the same file as the definition of a function. To apply one to a instance or class method, you must place it in the where clause of the instance or class declaration.

NOINLINE Do not inline the given function during core transformations. The function may be inlined during grin transformations. INLINE Inline this function whenever possible SUPERINLINE Always inline no matter what, even if it means making a local copy of the functions body. VCONSTRUCTOR Treat the function as a virtual constructor. CPR analysis and the worker/wrapper transforms will treat the function application as if it were a constructor. This implies 'NOINLINE'. NOETA By default, jhc eta-expands all class methods to help enable optimizations. This disables this optimization.

Rules/Specializations

RULES rewrite rules. These have the same syntax and behave similarly to GHC's rewrite rules, except 'phase' information is not allowed. SPECIALIZE create a version of a function that is specialized for a given type SUPERSPECIALIZE has the same effect as SPECIALIZE, but also places a run-time check in the generic version of the function to determine whether to call the specialized version.

Header Pragmas

These pragmas are only valid in the 'head' of a file, meaning they must come before the initial 'module' definition and in the first 4096 bytes of the file and must be preceded by and contain only characters in the ASCII character set.

OPTIONS_JHC : Specify extra options to use when processing this file. The options available are equivalent to the command line options, though, not all may have meaning when applied to a single file.

LANGUAGE : Specify various language options

Foreign Primitives

In addition to foreign imports of external functions as described in the FFI spec. Jhc supports 'primitive' imports that let you communicate primitives directly to the compiler. In general, these should not be used other than in the implementation of the standard libraries. They generally do little error checking as it is assumed you know what you are doing if you use them. All haskell visible entities are introduced via foreign declarations in jhc.

They all have the form

foreign import primitive "specification" haskell_name :: type

where "specification" is one of the following

seq : evaluate first argument to WHNF, then return the second argument

zero,one : the values zero and one of any primitive type.

const.C_CONSTANT : the text following const is directly inserted into the resulting C file

peek.TYPE : the peek primitive for raw value TYPE

poke.TYPE : the poke primitive for raw value TYPE

sizeOf.TYPE, alignmentOf.TYPE, minBound.TYPE, maxBound.TYPE, umaxBound.TYPE : various properties of a given internal type.

error.MESSAGE : results in an error with constant message MESSAGE.

constPeekByte : peek of a constant value specialized to bytes, used internally by Jhc.String

box : take an unboxed value and box it, the shape of the box is determined by the type at which this is imported

unbox : take an boxed value and unbox it, the shape of the box is determined by the type at which this is imported

increment, decrement : increment or decrement a numerical integral primitive value

fincrement, fdecrement : increment or decrement a numerical floating point primitive value

exitFailure__ : abort the program immediately

C-- Primitive : any C-- primitive may be imported in this manner.

Module Search Path

Modules in jhc are searched for based on their name as in other Haskell compilers. However in addition to searching for 'Data/Foo.hs' for the module 'Data.Foo', jhc will also search for 'Data.Foo.hs'.

Rank-N Polymorphism

Jhc supports higher ranked polymorphism. jhc will never infer types of higher rank, however when the context unambiguously specifies a higher ranked type, it will be infered. For instance, user supplied type annotations and arguments to data constructors defined to by polymorphic will work.

Existential types

Unboxed Values

Unboxed values in jhc are specified in a similar fashion to GHC however the lexical syntax is not changed to allow # in identifiers. # is still used in the syntax for various unboxed constructs, but normal Haskell rules apply to other Haskell values. The convention is to suffix such types with '_' to indicate their status as unboxed.

Differences from Haskell 98

Notable Differences from GHC

Jhc differs from GHC in certain ways that are allowed by Haskell 98, but might come as a surprise to some.

• An Int may be only 30 bits and may not observe simple binary truncation on overflow. If you need known bit width and binary semantics for your numbers then use the types in Data.Int and Data.Word. Overflow on Int or Word has undefined results.

• A Char may only preserve values within the Unicode range. Storing values greater than 0x10FFFF has undefined results.

• The Int and Word types are at most 32 bits, even on 64 bit architectures.

• All text based IO is performed according to the current locale. This means that Unicode works seamlessly, but older programs that assumed IO was performed by simple truncation of chars down to 8 bits will fail. Use the explicit binary routines if you need binary IO.

Differences That are Considered Misfeatures

These misfeatures will be fixed at some point.

• Integer corresponds to IntMax rather than an arbitrary precision type. As soon as a suitable arbitrary precision library emerges, it will be replaced.

• Ix is not derivable.

Basics

Unlike many other compilers, jhc is a native cross compiler. What this means is that every compile of jhc is able to create code for all possible target systems. This leads to many simplifications when it comes to cross compiling with jhc. Basically in order to cross compile, you need only pass the flag '--cross' to jhc, and pass an appropriate '-m' option to tell jhc what machine you are targetting. An example would be

; jhc --cross -mwin32 test/HelloWorld.hs

The targets list is extensible at run-time via the targets.ini file explained below.

targets.ini

This file determines what targets are available. The format consists of entries as follows.

[targetname]
key1=value
key2=value
key3+=value
merge=targetname2

merge is a special key meaning to merge the contents of another target into the current one. The configuration file is read in order, and the final value set for a given key is the one that is used.

An example describing how to cross compile for windows is as follows:

[win32]
gcc=i386-mingw32-gcc
cflags+=-mwindows -mno-cygwin
executable_extension=.exe
merge=i686

This sets the compiler to use as well as a few other options then jumps to the generic i686 routine. The special target [default] is always read before all other targets. If '--cross' is specified on the command line then this is the only implicitly included configuration, otherwise jhc will assume you are compiling for the current architecture and choose an appropriate target to include in addition to default.

jhc will attempt to read several targets.ini files in order. they are

$PREFIX/etc/jhc-$VERSION/targets.ini : this is the targets.ini that is included with jhc and contains the default options.

$PREFIX/etc/jhc-$VERSION/targets-local.ini : jhc will read this if it exists, it is used to specify custom system wide configuration options, such as the name of local compilers.

$HOME/.jhc/targets.ini : this is where a users local configuration information goes.

$HOME/etc/jhc/targets.ini : this is simply for people that prefer to not use hidden directories for configuration

The last value specified for an option is the one used, so a users local configuration overrides the system local version which overrides the built in options.

Options available

Jhc Core Type System

Jhc's core is based on a pure type system. A pure type system (also called a PTS) is actually a parameterized set of type systems. Jhc's version is described by the following.

Sorts  = (*, !, **, #, (#), ##, □)
Axioms = (*:**, #:##, !:**, **:□, ##:□)

-- sort kind
*   is the kind of boxed values
!   is the kind of boxed strict values
#   is the kind of unboxed values
(#) is the kind of unboxed tuples
-- sort superkind
**  is the superkind of all boxed value
##  is the superkind of all unboxed values
-- sort box
□   superkinds inhabit this

in addition there exist user defined kinds, which are always of supersort ##

The following Rules table shows what sort of abstractions are allowed, a rule of the form (A,B,C) means you can have functions of things of sort A to things of sort B and the result is something of sort C. Function in this context subsumes both term and type level abstractions.

Notice that functions are always boxed, but may be strict if they take an unboxed tuple as an argument. When a function is strict it means that it is represented by a pointer to code directly, it cannot be a suspended value that evaluates to a function.

These type system rules apply to lambda abstractions. It is possible that data constructors might exist that cannot be given a type on their own with these rules, even though when fully applied it has a well formed type. An example would be unboxed tuples. This presents no difficulty as one concludes correctly that it is a type error for these constructors to ever appear when not fully saturated with arguments.

as a shortcut we will use *# to mean every combination involving * and #, and so forth. 
for instance, (*#,*#,*) means the set (*,*,*) (#,*,*) (*,#,*) (#,#,*)

Rules =
   (*#!,*#!,*)  -- functions from values to values are boxed and lazy
   (*#!,(#),*)  -- functions from values to unboxed tuples are boxed and lazy
   ((#),*#!,!)  -- functions from unboxed tuples to values are boxed and strict
   ((#),(#),!)  -- functions from unboxed tuples to unboxed tuples are boxed and strict
   (**,*,*)     -- may have a function from an unboxed type to a value
   (**,#,*)
   (**,!,*)
   (**,**,**)  -- we have functions from types to types
   (**,##,##)  -- Array__ a :: #

The defining feature of boxed values is

_|_ :: t iff t::*

This PTS is functional but not injective

The PTS can be considered stratified into the following levels

□                - sort box
**,##,           - sort superkind
*,#,(#),!        - sort kind
Int,Bits32_,Char - sort type
3,True,"bob"     - sort value

∀s1:□ ∀s2:□ ∀k1:s1 ∀k2:s2 ∀t1:k1 ∀t2:k2 . (# t1, t2 #)

         □             - the box
        / \
      **   ##          - superkind
      /\     \
     *  !     #   (#)  - kind

           □□            - sort superbox
          /  \
         □    (□)        - sort box
        / \      \
      **   ##     (##)   - sort superkind
      /\     \    | 
     *  !     #   (#)    - sort kind

The Run Time System

Jhc is very minimalist in that it does not have a precompiled run time system, but rather generates what is needed as part of the compilation process. However, we call whatever conventions and binary layouts used in the generated executable the run time system. Since jhc generates the code anew each time, it can build a different 'run time' based on compiler options, trading things like the garbage collector as needed or changing the closure layout when we know we have done full program optimization. This describes the 'native' layout upon which other conventions are layered.

A basic value in jhc is represented by a 'smart pointer' of c type sptr_t. a smart pointer is the size of a native pointer, but can take on different roles depending on a pair of tag bits.

smart pointers take on a general form as follows:

-------------------------
|    payload        | GL|
-------------------------

  G - if set, then the garbage collector should not treat value as a pointer to be followed
  L - lazy, this bit being set means the value is not in WHNF

A raw sptr_t on its own in the wild can only take on one of the following values:

-------------------------
|    raw value      | 10|
-------------------------

-------------------------
|    whnf location  | 00|
-------------------------

-------------------------
|   lazy location   | 01|
-------------------------

A raw value can be anything and not necessarily a pointer in general, a WHNF location is a pointer to some value in WHNF. The system places no restrictions on what is actually pointed to by a WHNF pointer, however the garbage collector in use may. In general, the back end is free to choose what to place in the raw value field or in what a WHNF points to with complete freedom. If an implementation sees the L bit is clear, it can pass on the smart pointer without examining it knowing the value is in WHNF.

A lazy location points to a potential closure or an indirection to a WHNF value. The lazy location is an allocated chunk of memory that is at least one pointer long. the very first location in a closure must be one of the following.

-------------------------
| raw value or whnf  |X0|
-------------------------

An evaluated value, interpreted exactly as above. one can always replace any occurance of a lazy location with an evaluated indirecton.

-------------------------
|    code pointer   | 11|
-------------------------
|     data ...          |

This is something to evaluate, code pointer is a pointer to a function that takes the memory location as its only argument, the called function is in charge of updating the location if needed.

note that it is invalid to have a lazy location point to another lazy location. there is only ever one level of indirection allowed, and only from lazy locations

note that a partial application is just like any other value in WHNF as far as the above is concered. It happens to possibly contain a code pointer.