| 1 | Installation guide for Halibut |
| 2 | ============================== |
| 3 | |
| 4 | This file is a guide to building and installing the documentation |
| 5 | utility `Halibut' from its source archive. |
| 6 | |
| 7 | If you are reading this, then you have probably already unpacked the |
| 8 | source archive somewhere. |
| 9 | |
| 10 | Building Halibut |
| 11 | ---------------- |
| 12 | |
| 13 | If you have GNU make and gcc, you should simply be able to type |
| 14 | `make'. The Makefile will generate a `build' subdirectory, and will |
| 15 | put all the object files and binaries in there. |
| 16 | |
| 17 | In a release archive, the Makefile will also check the source files |
| 18 | against a list of MD5 checksums, and if they match it will |
| 19 | automatically add the correct version number to the build. This is |
| 20 | _not_ a secure measure intended to enforce that only approved |
| 21 | Halibut sources are ever built into a binary with a given version |
| 22 | number; it is merely a sanity check against heavily modified copies |
| 23 | _accidentally_ confusing users expecting standard versions of |
| 24 | Halibut. Distribution maintainers are entirely at liberty, if they |
| 25 | choose, to modify Halibut source files as appropriate for their |
| 26 | distribution and then have the resulting binary call itself by the |
| 27 | original version number. If you run `make VERSION=x.y', the |
| 28 | resulting Halibut binary will call itself version x.y irrespective |
| 29 | of the md5sum manifest. (You may also need to do this if your build |
| 30 | system does not have the md5sum program.) |
| 31 | |
| 32 | Halibut unfortunately does not yet come with an autoconf-generated |
| 33 | makefile, so if you do not have these utilities then you will have |
| 34 | to do the build manually. Look in the master `Makefile' to find the |
| 35 | list of source modules (they will be listed on the line starting |
| 36 | `MODULES :=', and continued on lines starting `MODULES +='), compile |
| 37 | those files with the C compiler of your choice, and link them |
| 38 | together into a binary. In addition to the modules on that list, you |
| 39 | will also need to compile `version.c', and if you wish your Halibut |
| 40 | binary to identify itself with a version number then you will have |
| 41 | to define the preprocessor symbol `VERSION' to the required version |
| 42 | number string. On Unix this can be done with a command such as |
| 43 | |
| 44 | cc -c -DVERSION=\"0.9\" version.c |
| 45 | |
| 46 | Halibut's source files are intended to be almost entirely portable |
| 47 | ANSI C. If they fail to compile and run correctly on your compiler, |
| 48 | this might very well be considered a bug. |
| 49 | |
| 50 | Building the Halibut manual |
| 51 | --------------------------- |
| 52 | |
| 53 | Once you have built Halibut itself, you might well want to build its |
| 54 | manual. If you're using GNU make, you can do this just by changing |
| 55 | into the `doc' subdirectory and typing `make'. (This relies on the |
| 56 | Halibut binary you built in the previous step being present in the |
| 57 | `build' subdirectory.) |
| 58 | |
| 59 | Failing that, you will need to read the Makefile and run a manual |
| 60 | Halibut command, of the form |
| 61 | |
| 62 | halibut --text=halibut.txt --html blurb.but intro.but [...] index.but |
| 63 | |
| 64 | (The precise list of .but files is given at the top of doc/Makefile.) |
| 65 | |
| 66 | This will build plain text documentation in `halibut.txt', and a set |
| 67 | of HTML files (*.html). It will also build a short man page |
| 68 | `halibut.1', although this is by no means a replacement for the full |
| 69 | manual. |
| 70 | |
| 71 | Installing Halibut |
| 72 | ------------------ |
| 73 | |
| 74 | Halibut requires no additional data files. Simply install the |
| 75 | binary, man page and full documentation in appropriate places for |
| 76 | your system. |