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