73a05796 |
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 | |
574825cf |
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 | |
73a05796 |
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. |