demos/tunala/INSTALL

   1 There are two ways to build this code;
   2
   3 (1) Manually
   4
   5 (2) Using all-singing all-dancing (all-confusing) autotools, ie. autoconf,
   6 automake, libtool, and their little friends (autoheader, etc).
   7
   8 =================
   9 Building Manually
  10 =================
  11
  12 There is a basic "Makefile" in this directory that gets moved out of the way and
  13 ignored when building with autoconf et al. This Makefile is suitable for
  14 building tunala on Linux using gcc. Any other platform probably requires some
  15 tweaking. Here are the various bits you might need to do if you want to build
  16 this way and the default Makefile isn't sufficient;
  17
  18 * Compiler: Edit the "CC" definition in Makefile
  19
  20 * Headers, features: tunala.h controls what happens in the non-autoconf world.
  21   It, by default, assumes the system has *everything* (except autoconf's
  22   "config.h") so if a target system is missing something it must define the
  23   appropriate "NO_***" symbols in CFLAGS. These include;
  24
  25   - NO_HAVE_UNISTD_H, NO_HAVE_FCNTL_H, NO_HAVE_LIMITS_H
  26     Indicates the compiling system doesn't have (or need) these header files.
  27   - NO_HAVE_STRSTR, NO_HAVE_STRTOUL
  28     Indicates the compiling system doesn't have these functions. Replacements
  29     are compiled and used in breakage.c
  30   - NO_HAVE_SELECT, NO_HAVE_SOCKET
  31     Pointless symbols - these indicate select() and/or socket() are missing in
  32     which case the program won't compile anyway.
  33
  34   If you want to specify any of these, add them with "-D" prefixed to each in
  35   the CFLAGS definition in Makefile.
  36
  37 * Compilation flags: edit DEBUG_FLAGS and/or CFLAGS directly to control the
  38   flags passed to the compiler. This can also be used to change the degree of
  39   optimisation.
  40
  41 * Linker flags: some systems (eg. Solaris) require extra linker flags such as;
  42   -ldl, -lsocket, -lnsl, etc. If unsure, bring up the man page for whichever
  43   function is "undefined" when the linker fails - that usually indicates what
  44   you need to add. Make changes to the LINK_FLAGS symbol.
  45
  46 * Linker command: if a different linker syntax or even a different program is
  47   required to link, edit the linker line directly in the "tunala:" target
  48   definition - it currently assumes the "CC" (compiler) program is used to link.
  49
  50 ======================
  51 Building Automagically
  52 ======================
  53
  54 Automagic building is handled courtesy of autoconf, automake, and libtool. There
  55 is in fact two steps required to build, and only the first has to be done on a
  56 system with these tools installed (and if I was prepared to bloat out the CVS
  57 repository, I could store these extra files, but I'm not).
  58
  59 First step: "autogunk.sh"
  60 -------------------------
  61
  62 The "./autogunk.sh" script will call all the necessary autotool commands to
  63 create missing files and run automake and autoconf. The result is that a
  64 "./configure" script should be generated and a "Makefile.in" generated from the
  65 supplied "Makefile.am". NB: This script also moves the "manual" Makefile (see
  66 above) out of the way and calls it "Makefile.plain" - the "ungunk" script
  67 reverses this to leave the directory it was previously.
  68
  69 Once "ungunk" has been run, the resulting directory should be able to build on
  70 other systems without autoconf, automake, or libtool. Which is what the second
  71 step describes;
  72
  73 Second step: "./configure"
  74 --------------------------
  75
  76 The second step is to run the generated "./configure" script to create a
  77 config.h header for your system and to generate a "Makefile" (generated from
  78 "Makefile.in") tweaked to compile on your system. This is the standard sort of
  79 thing you see in GNU packages, for example, and the standard tricks also work.
  80 Eg. to override "configure"'s choice of compiler, set the CC environment
  81 variable prior to running configure, eg.
  82
  83     CC=gcc ./configure
  84
  85 would cause "gcc" to be used even if there is an otherwise preferable (to
  86 autoconf) native compiler on your system.
  87
  88 *IMPORTANT* It's highly recommended to pass "--disable-shared" to the configure
  89 script. Otherwise, libtool may elect to build most of the code as a
  90 shared-library, hide various bits of it in dotted directories and generating
  91 wrapper scripts in place of the linked binary. The autotool stuff, when "make
  92 install" is run (which you probably won't want to do for this dinky little
  93 thing) will unravel all that mess and either install a small executable +
  94 shared-lib or will install a linked executable. Passing the above flag ensures
  95 this is all done statically even if the platform supports building and using
  96 shared-libraries. Ie;
  97
  98     ./configure --disable-shared
  99
 100 After this run "make" and it should build the "tunala" executable.
 101
 102 Notes
 103 -----
 104
 105 - Some versions of autoconf (or automake?) generate a Makefile syntax that gives
 106   trouble to some "make" programs on some systems (eg. OpenBSD). If this
 107   happens, either build 'Manually' (see above) or use "gmake" instead of "make".
 108   I don't like this either but like even less the idea of sifting into all the
 109   script magic crud that's involved.
 110
 111 - On a solaris system I tried, the "configure" script specified some broken
 112   compiler flags in the resulting Makefile that don't even get echoed to
 113   stdout/err when the error happens (evil!). If this happens, go into the
 114   generated Makefile, find the two affected targets ("%.o:" and "%.lo"), and
 115   remove the offending hidden option in the $(COMPILE) line all the sludge after
 116   the two first lines of script (ie. after the "echo" and the "COMPILE" lines).
 117   NB: This will probably only function if "--disable-shared" was used, otherwise
 118   who knows what would result ...
 119