The INSTALL file in the topmost directory of the Knit source tree contains an abbreviated version of these instructions.
Knit consists of the following programs:
knit, knitdoc, and knitGenBundles are written in the Haskell programming language, and the helper programs rename_dot_o_files and knit_c_parser are written in C. Because Knit can be somewhat tricky to compile, most users will want to download the Knit tools in precompiled form. Users who want to work on Knit itself, however, will need to be able to compile Knit from source.
FreeBSD and Linux are the current Knit development platforms. If you build Knit on an interesting platform, the Knit developers would love to know about it. Of course, if the build fails, they would like to know about that, too! Send build reports, bug reports, praise and damnation to knit-users@flux.cs.utah.edu.
Knit is available on the World Wide Web under http://www.cs.utah.edu/flux/knit/. Currently, Knit is distributed in two forms: as precompiled binaries for a variety of operating systems, and as source code. We strongly recommend that you use the precompiled binaries for your platform if available. (Please contact the Knit authors if precompiled binaries for your platform are not available. If demand warrants, your platform may be added to the supported set.)
If you are using a binary distribution of Knit, you should skip the instructions below and proceed to Section 2.3.
In order to build Knit from source, you will need:
Once you have the above-listed tools, you will need to (1) unpack the Knit source distribution tar file and (2) create a build tree to contain the object files. Assuming that you did these things in your home directory, your directory setup would look something like this:
Before configuring or compiling Knit, you must first have the libelf library and headers available on your system. If your operating system has libelf preinstalled, great: you are done with this step. However, if your system does not come with libelf, you must download and compile (and optionally install) libelf for yourself before proceeding. See Section 2.2 for download and version information.
| WARNING: If you have problems with the Knit rename_dot_o_files program — i.e., if it seems to produce invalid object files — you may need to build libelf so that it does not use the mmap system call to manipulate files. (The Knit authors have seen this problem occur when the object file is located in an NFS-mounted filesystem.) To build libelf so that it does not use mmap, first configure the library normally, and then comment out the HAVE_MMAP definition in the generated config.h file. Finally, build and install the library. |
Given the directory setup described in Section 2.2, you would type the following commands to configure Knit for your operating system:
The configure script in the root of the Knit source tree is an ordinary configure script, generated by GNU autoconf. Type “configure --help” to see all of the script’s command line options. In addition to all of the standard options accepted by autoconf-generated scripts, Knit’s configure script accepts the following Knit-specific options:
Additionally, the Knit configure script examines the values of the following environment variables:
Finally, you are ready to compile the Knit tools! If you are using the Glasgow Haskell Compiler, type the following commands to build Knit and its auxiliary programs:
Assuming all goes well, these commands should produce all of the Knit programs that need to be compiled.
If you are using Hugs, type the following instead:
These commands will produce some object files and the C-based helper programs only (i.e., knit_c_parser and rename_dot_o_files). Since Hugs is an interpreter, there is no need to compile the Haskell-based programs.
Of course, if you are using a precompiled binary release of Knit, you do not need to build the binaries at all: you already have them! But you still have to install the programs — read on.
You can install the Knit compiler programs in a “standard” place on your system by typing “make install” in the bin subdirectory of your Knit build tree (in our running example, ~/obj/bin).
Special instructions for binary distributions: If you are using a binary distribution of Knit, you will nevertheless need to run the Knit configure script, which will (1) tailor certain Knit scripts to your system, (2) configure the installation process for your system, and (3) produce the Knit example program Makefiles. We encourage you to run the configure script in a directory that is separate from your Knit distribution tree, because Knit will produce many files when processing the examples. So, to configure and install a binary distribution, type something like the following:
Whether you use a source or binary distribution, by default, the root installation directory is /usr/local. You can change this default by specifying the --prefix option to configure, e.g.:
It is not necessary to install Knit in order to use the provided example programs (described in the next section) or to build your own Knit-based programs.
Knit comes with a small set of example programs; these are located in the examples subdirectory of the distribution source tree. Running your newly compiled Knit tools on the provided examples is easy. In a sentence: go to the examples subdirectory of your Knit object tree and type make. This will build all of examples. If everything builds, congratulations! You are now a “techknitian”!
The various example programs are described in greater detail in Chapter 4.
The software described below is not part of Knit, but is often used in conjunction with Knit.
For projects involving operating systems or similar low-level software, you may want to use Knit in conjunction with the OSKit. The OSKit is a framework and set of modularized components and library code, together with extensive documentation, for the construction of operating system kernels, servers, and other OS-level tools. Its purpose is to provide much of the infrastructure “grunge” that usually takes up a large percentage of development time in any operating system or OS-related project, and allow developers to concentrate their efforts on the unique and interesting aspects of the new OS in question. The OSKit is available on the World Wide Web under http://www.cs.utah.edu/flux/oskit/.
Recent versions of the OSKit can be configured to work with Knit. Instructions for using Knit with the OSKit are in Chapter 6. Knit-specific files in the OSKit are located in a subdirectory called oskit/knit. Look there for unit definition files and related files. Refer to the OSKit documentation for further information about the OSKit.
| WARNING: Because Knit and the OSKit are both active and evolving projects, you must be careful to get a “matched set” in order to use them together! Knit version 1.0.0 is intended to work with OSKit version 20010214 (a snapshot release). Later versions of either system may not work with previous versions of the other — backward compatibility is not guaranteed! |
If you use Knit’s “flattening” optimization on certain C sources, including the OSKit, you may need to use a special version of gcc in order to compile your Knit-generated C code. This special version of gcc must ignore certain type errors that may be introduced by Knit, because Knit does not unify identical type declarations that originate in two separate C files. This sounds really dodgy, but we are assuming that you have already built your system without flattening using a normal C compiler. If the unflattened version is free of type errors, then compiling with flattening and the hacked compiler should work just fine.
The instructions for producing a patched version of gcc are contained in the file unsupported/gcc.patch in the Knit distribution tree. The effect of the patch is to allow assignments to variables when the assigned value has a different type, so long as the types of the variable and value have the same storage size. This patch relaxes the C type rules and is okay as long as your program can be compiled in a normal way by an unpatched version of gcc.
| WARNING: If you make a patched version of gcc, you should be careful to install it in a very special place with a very special name, so that nobody will use it accidentally to compile anything other than Knit-generated code. |