mdw@git.distorted.org.uk Git - sgt/halibut/blob - INSTALL

   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.