# The hmake-config utility

Usage
Viewing the compiler database
Updating the compiler database

Hmake-config is a small utility for managing your hmake compiler database. It can show a summary of which compilers are known, or it can update the database (held in an hmakerc file) by adding or deleting knowledge about a particular Haskell compiler, or changing the default compiler.

### Usage

The basic option summary is:

        Usage: hmake-config [cfgfile] new
               hmake-config [cfgfile] list [compiler]
               hmake-config [cfgfile] [add|delete|default] compiler

The optional cfgfile is your chosen location of the database of known compilers, should you happen not to wish to use the default locations. (See section About the compiler database below.)

### Viewing the compiler database

list | A summary of all compilers known by hmake is listed, one compiler per line. The default compiler is also reported.
list comp | Full details for the compiler comp are shown.

For instance:

        $ hmake-config list
        Global config file is:
            /usr/local/lib/hmake/ix86-Linux/hmakerc
        Personal config file is:
            ~/.hmakerc/ix86-Linux
        Known compilers:
            nhc98	(v1.14)
            hbc	(0.9999.5b,)
            ghc-4.08.2	(4.08.2)
            ghc-5.02.3	(5.02.3)
            ghc	(5.02.3)
            /usr/local/bin/nhc98	(v1.14)
            /usr/local/bin/hbc	(0.9999.5b,)
            /usr/local/bin/ghc	(5.04.2)
        Default compiler:
            nhc98

        $ hmake-config list /usr/local/bin/ghc
        CompilerConfig
          { compilerStyle = ghc
          , compilerPath = "/usr/local/bin/ghc"
          , compilerVersion = "5.04.2"
          , includePaths = ["/usr/local/lib/ghc-5.04.2/imports/base"
                           ,"/usr/local/lib/ghc-5.04.2/imports/haskell98"
                           ]
          , cppSymbols = ["__GLASGOW_HASKELL__=504"]
          , extraCompilerFlags = []
          , isHaskell98 = True
          }

### Updating the compiler database

Important: the very first time you use hmake-config to update the compiler database, you must create your own personal config, using the new option (see details in the table below).

To update your compiler database, one of the actions add, delete, or default is applied to the compiler given on the commandline. (If no action is given, add is assumed.) The compiler can be specified either as a simple name which resolves to an executable command name via the normal `$PATH` mechanism, or as an absolute pathname to the compiler (these are treated as different database entries), e.g.

        $ hmake-config add ghc		# takes the first ghc in the $PATH
        $ hmake-config add /usr/bin/ghc	# takes a specific version

new | Start a completely fresh hmakerc configuration file. If the file already existed, it is overwritten. (If no hmakerc file was explicitly specified, the default "personal" location within your home directory is assumed.)
add comp | The specified compiler is probed for various pieces of information, including its version, and the paths to directories holding interface files for standard libraries. If everything is OK, that compiler's configuration is added to the hmakerc file, or if it was already known, the configuration is updated.
add-dyn comp | The specified compiler is added to the hmakerc file, but it is probed for its version/interface information dynamically every time it is used, instead of only once statically right now. This option is especially useful if you frequently change the compiler that appears first in your PATH variable and don't want to be bothered to have to tell hmake about those changes every time.
delete comp | All configuration information for the specified compiler is removed from the hmakerc file.
default comp | Provided the specified compiler is already known in the hmakerc file, it is made the default compiler. If it is not known, the default remains unchanged and an error is reported.

### About the compiler database

The hmakerc file manipulated by hmake-config is written in plain text, as a structured Haskell value. You are free to read it, and edit it by hand if you wish. (Be aware however that a later use of hmake-config add may override any changes you make.)

In fact, there are potentially two hmakerc files that might be involved in any transaction with hmake-config. Firstly, there is the "global" config file, normally created at the time hmake is installed: it resides in the system directories (usually at `/usr/local/lib/hmake/$MACHINE/hmakerc`), and cannot be changed except by the system administrator. Then, there may be a "personal" config file, residing in the user's home directory (always at `$HOME/.hmakerc/$MACHINE`): it permits an individual to override (point-wise) the system-wide configuration, for instance, if a different version of a compiler comes earlier in the user's PATH, or if the user prefers a different default compiler.

When an hmake-config command-line does not name a specific hmakerc file, it reads both the global and the personal files, but writes only to the personal file.

When an hmake-config command-line explicitly names an hmakerc file, the named file is used for all reading and writing, instead of the "global" and the "personal" files. (The command new must be used to initialise the file before it can be used.) Remember that if you use a non-standard location for your named hmakerc file, you will also need to tell hmake proper where it is on every invocation.

### Notes

To support users who may have access to heterogeneous machines on a network with a shared filespace, there is a separate hmakerc file for each machine architecture they use. This is very important to avoid conflicts between versions of compilers. (In the description above, `$MACHINE` represents the machine architecture as reported by ``harch``, not the actual machine name.)

It is difficult to detect the exact directories in which hbc expects to find interface files for standard libraries. Thus hmake-config relies on the environment variables `HBCDIR` or `LMLDIR` for the correct location.

When the system administrator wishes to update the global config file, it is sufficient just to name it explicitly in an hmake-config command, assuming the file permissions are set appropriately.

The latest updates to this software are available on the WWW from `http://www.haskell.org/hmake/` ( `http://www.cs.york.ac.uk/fp/hmake/`)

Information last updated: 1st Sept 2005
York Functional Programming Group
Malcolm.Wallace@cs.york.ac.uk