home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 February / CHIP_2_98.iso / doc / HOWTO / mini / Software-Building < prev    next >
Text File  |  1997-08-18  |  17KB  |  387 lines
  1.   Building Software Packages for Linux
  2.   Mendel Leo Cooper <mailto:thegrendel@theriver.com>
  3.   http://personal.riverusers.com/~thegrendel/
  4.   v1.3, 13 August 1997
  5.  
  6.   This document is a guide to building "generic" UNIX software distribu¡
  7.   tions under Linux.
  8.  
  9.   1.  Introduction
  10.  
  11.   Many software packages for the various flavors of UNIX, including
  12.   Linux, are distributed as compressed archives of source files.  The
  13.   same package may be "built" to run an various target machines, and
  14.   this saves the author of the software from having to produce multiple
  15.   distributions. A single distribution of a software package may thus
  16.   end up running, in various incarnations, on an Intel box, a DEC Alpha,
  17.   a RISC workstation, or even a mainframe.  Unfortunately, this puts the
  18.   responsibility of actually "building" the software on the end user,
  19.   the de facto "system administrator", the fellow sitting at the
  20.   keyboard...  you.  Take heart, though, the process is not nearly as
  21.   terrifying or mysterious as it seems, and this guide will attempt to
  22.   demonstrate just that.
  23.  
  24.   2.  Getting Started
  25.  
  26.   You have downloaded or otherwise retrieved a software package.  Most
  27.   likely it is archived (tarred) and compressed (gzipped), in .tar.gz or
  28.   .tgz form. It must first be copied to a working directory. Then it is
  29.   necessary to untar and gunzip it. The appropriate command is tar xzvf
  30.   filename, where filename is the name of the software file, of course.
  31.   The de-archiving process will usually install the appropriate files in
  32.   subdirectories it will create.  Note that if the package name has a .Z
  33.   suffix, it will require uncompress PACKAGENAME, then tar xvf
  34.   PACKAGENAME rather than the above procedure.
  35.  
  36.   Sometimes the archived file must be untarred and installed from the
  37.   user's home directory, or perhaps in a certain other directory,
  38.   according to the package's config info.  Should you get an error
  39.   message attempting to untar it, this may be the cause. Read the
  40.   package docs (especially the README and/or Install files, if present)
  41.   and edit the config files and/or Makefiles and Imake files, as
  42.   necessary, consistent with the installation instructions. Some
  43.   software packages permit automating this process by running make
  44.   install to emplace the binaries in the appropriate system areas.
  45.  
  46.   You are now ready to proceed to the build stage of the process.
  47.  
  48.   3.  Using Make
  49.  
  50.   The Makefile is the key to the build process. In its simplest form, a
  51.   Makefile is a script for compiling or building the "binaries", the
  52.   executable portions of a program. The Makefile can also provide a
  53.   means of updating a software package without having to recompile every
  54.   single source file in it, but that is a different story (or a
  55.   different article).
  56.  
  57.   At some point, the Makefile launches cc or gcc. This is actually a
  58.   preprocessor, a C (or C++) compiler, and a linker, invoked in that
  59.   order.  This process converts the source into the binaries, the actual
  60.   executables.
  61.  
  62.   Only the simplest software uses a generic Makefile. More complex
  63.   installations require tailoring the Makefile according to the location
  64.   of libraries, include files, and resources on your particular machine.
  65.   This is especially the case when the build needs the X11 libraries to
  66.   install. Imake and xmkmf accomplish this task.
  67.  
  68.   An Imakefile is, to quote the man page, a "template" Makefile. The
  69.   imake utility constructs a Makefile appropriate for your system from
  70.   the Imakefile. In almost all cases, however, you would run xmkmf, a
  71.   shell script that invokes imake, a front end for it.  Check the README
  72.   or INSTALL file included in the software archive for specific
  73.   instructions.  Read the imake and xmkmf man pages for a more detailed
  74.   analysis of the procedure..
  75.  
  76.   Be aware that xmkmf and make may need to be invoked as root,
  77.   especially when doing a make install to move the binaries over to the
  78.   /usr/bin or /usr/local/bin directories.  Using make as an ordinary
  79.   user without root privileges will likely result in write access denied
  80.   error messages because you lack write permission to system
  81.   directories. Check also that the binaries created have the proper
  82.   execute permissions for you and any other appropriate users.
  83.  
  84.   Invoking xmkmf uses the imake file to build a new Makefile appropriate
  85.   for your system. It sets the variables and defines the library
  86.   locations for the compiler and linker.  Sometimes, there will be no
  87.   imake file, instead there will be an INSTALL script that will
  88.   accomplish this purpose. The README file included with the
  89.   distribution will usually explain the install procedure.
  90.  
  91.   Your general installation procedure will therefore be:
  92.  
  93.   ╖  Read the README file.
  94.  
  95.   ╖  Run xmkmf or the INSTALL script.
  96.  
  97.   ╖  If necessary, run make clean or make depend
  98.  
  99.   ╖  Run make.
  100.  
  101.   ╖  If necessary, run make install
  102.  
  103.   4.  Troubleshooting
  104.  
  105.   If xmkmf and/or make succeeded without errors, you may proceed to the
  106.   ``next section''.  However, in "real life", few things work right the
  107.   first time.  This is when your resourcefulness is put to the test.
  108.  
  109.   4.1.  Link Errors
  110.  
  111.   ╖  Suppose make fails with a Link error: -lX11: No such file or
  112.      directory, even after xmkmf has been invoked. This may mean that
  113.      the imake file was not set up properly. Check the first part of the
  114.      Makefile for lines such as:
  115.  
  116.   LIB=            -L/usr/X11/lib
  117.   INCLUDE=        -I/usr/X11/include/X11
  118.   LIBS=           -lX11 -lc -lm
  119.  
  120.   The -L and -I switches tell the compiler and linker where to look for
  121.   the library and include files, respectively. In this example, the X11
  122.   libraries should be in the /usr/X11/lib directory, and the X11 include
  123.   files should be in the /usr/X11/include/X11 directory. If this is
  124.   incorrect for your machine, make the necessary changes to the Makefile
  125.   and try the make again.
  126.  
  127.   ╖  -----------------------------------------------------------------
  128.  
  129.   ╖  In a very few cases, running ldconfig as root may be the solution:
  130.  
  131.      # /etc/ldconfig -n /lib will update the shared library symbolic
  132.      links. This should not be necessary under normal circumstances.
  133.  
  134.   ╖  -----------------------------------------------------------------
  135.  
  136.   ╖  Yet another thing to try if xmkmf fails is the following script:
  137.  
  138.                 make -DUseInstalled -I/usr/X386/lib/X11/config
  139.  
  140.   ╖  -----------------------------------------------------------------
  141.  
  142.   ╖  Sometimes the source needs the older release X11R5 libraries to
  143.      build.  If you have the R5 libs in /usr/X11R6/lib (you were given
  144.      the option of having them when first installing Linux), then you
  145.      need only ensure that you have the links that the software needs to
  146.      build.  The R5 libs are named libX11.so.3.1.0, libXaw.so.3.1.0, and
  147.      libXt.so.3.1.0. You generally need links, such as libX11.so.3 ->
  148.      libX11.so.3.1.0. Possibly the software will also need a link of the
  149.      form libX11.so -> libX11.so.3.1.0.  Of course, to create a
  150.      "missing" link, use the command ln -s libX11.so.3.1.0 libX11.so, as
  151.      root.
  152.  
  153.   4.2.  Other Problems
  154.  
  155.   ╖  An installed Perl or shell script gives you a No such file or
  156.      directory error message. In this case, check the file permissions
  157.      to make sure the file is executable and check the file header to
  158.      ascertain whether the shell or program invoked by the script is in
  159.      the place specified.  For example, the scrip may begin with:
  160.  
  161.        #!/usr/local/bin/Perl
  162.  
  163.   If Perl is in fact installed in your /usr/bin directory instead of the
  164.   /usr/local/bin one, then the script will not run. Edit and correct the
  165.   script file header in such a case.
  166.  
  167.   ╖  -----------------------------------------------------------------
  168.  
  169.   ╖  Some X11 software requires the Motif libraries to build.  The
  170.      standard Linux distributions do not have the Motif libraries
  171.      installed, and at present Motif costs an extra $100-$200 (though
  172.      the freeware Lesstif may also work in many cases). If you need
  173.      Motif to build a certain package, but lack the Motif libraries, it
  174.      may be possible to obtain statically linked binaries. Static
  175.      linking incorporates the library routines in the binaries
  176.      themselves.  This results in much larger binary files, but the code
  177.      will run even on systems lacking the libraries.
  178.  
  179.   4.3.  Where to go for more help
  180.  
  181.   In my experience, about 25% of applications build "right out of the
  182.   box". Another 50% or so can be persuaded to build with an effort
  183.   ranging from trivial to herculean. That still means a significant
  184.   number of packages will not build no matter what. Even then, the Intel
  185.   ELF and/or a.out binaries for these might possibly be found at Sunsite
  186.   <ftp://sunsite.unc.edu>, the TSX-11 archive <ftp://tsx-11.mit.edu> or
  187.   other places.  Perhaps the author of the software can supply the
  188.   binaries compiled for your particular flavor of machine.
  189.  
  190.   Note that if you obtain precompiled binaries, you will need to check
  191.   for compatibility with your system:
  192.  
  193.   ╖  The binaries must run on your hardware (i.e., Intel x86).
  194.  
  195.   ╖  The binaries must be compatible with your kernel (i.e., a.out or
  196.      ELF).
  197.  
  198.   If all else fails, you may find help in the appropriate newsgroups,
  199.   such as comp.os.linux.x or comp.os.linux.development.  Once in a
  200.   while, though, you are just plain out of luck, but hey, it was fun
  201.   trying.
  202.  
  203.   5.  Final Steps
  204.  
  205.   Read the software package documentation to determine whether certain
  206.   environmental variables need setting (in .bashrc or .cshrc) and if the
  207.   .Xdefaults and .Xresources files need customizing.
  208.  
  209.   There may be an applications default file, usually named Xfoo.ad in
  210.   the original Xfoo distribution. If so, edit the Xfoo.ad file to
  211.   customize it for your machine, then rename (mv) it Xfoo and install it
  212.   in the /usr/lib/X11/app-defaults directory, as root.  Failure to do
  213.   this may cause the software to misbehave or even refuse to run.
  214.  
  215.   Most software packages come with one or more preformatted man pages.
  216.   As root, copy the Xfoo.man file to the appropriate /usr/man directory
  217.   (man1 - man9), and rename it accordingly.  For example, if Xfoo.man
  218.   ends up in /usr/man/man4, it should be renamed Xfoo.4 (mv Xfoo.man
  219.   Xfoo.4).
  220.  
  221.   Note that some or all of the above procedures may in certain cases be
  222.   handled automatically by a make install. If so, the README or INSTALL
  223.   doc file will specify this.
  224.  
  225.   6.  First Example: Xscrabble
  226.  
  227.   Matt Chapman's Xscrabble seemed like a program that would be
  228.   interesting to have, since I happen to be an avid Scrabble[TM] player.
  229.   I downloaded it, uncompressed it,  and built it following the
  230.   procedure in the README file:
  231.  
  232.             xmkmf
  233.             make Makefiles
  234.             make includes
  235.             make
  236.  
  237.   Of course it did not work...
  238.  
  239.   ______________________________________________________________________
  240.   gcc -o xscrab -O2 -O -L/usr/X11R6/lib
  241.   init.o xinit.o misc.o moves.o cmove.o main.o xutils.o mess.o popup.o
  242.   widgets.o display.o user.o CircPerc.o
  243.   -lXaw -lXmu -lXExExt -lXext -lX11 -lXt -lSM -lICE -lXExExt -lXext -lX11
  244.   -lXpm -L../Xc -lXc
  245.  
  246.   BarGraf.o(.text+0xe7): undefined reference to `XtAddConverter'
  247.   BarGraf.o(.text+0x29a): undefined reference to `XSetClipMask'
  248.   BarGraf.o(.text+0x2ff): undefined reference to `XSetClipRectangles'
  249.   BarGraf.o(.text+0x375): undefined reference to `XDrawString'
  250.   BarGraf.o(.text+0x3e7): undefined reference to `XDrawLine'
  251.   etc.
  252.   etc.
  253.   etc...
  254.   ______________________________________________________________________
  255.  
  256.   I enquired about this in the comp.os.linux.x newsgroup, and someone
  257.   kindly pointed out to me that apparently the Xt, Xaw, Xmu, and X11
  258.   libs were not being found at the link stage. Hmmm...
  259.  
  260.   There were two main Makefiles, and the one in the src directory caught
  261.   my interest. One line in the Makefile defined LOCAL_LIBS as:
  262.   LOCAL_LIBS = $(XAWLIB) $(XMULIB) $(XTOOLLIB) $(XLIB) Here were
  263.   references to the libs not being found by the linker.
  264.  
  265.   Looking for the next reference to LOCAL_LIBS, I saw on line 495 of
  266.   that Makefile:
  267.  
  268.              $(CCLINK) -o $@ $(LDOPTIONS) $(OBJS) $(LOCAL_LIBS) $(LDLIBS)
  269.        $(EXTRA_LOAD_FLAGS)
  270.  
  271.   Now what were these LDLIBS?
  272.  
  273.         LDLIBS = $(LDPOSTLIB) $(THREADS_LIBS) $(SYS_LIBRARIES)
  274.   $(EXTRA_LIBRARIES)
  275.  
  276.   The SYS_LIBRARIES were:
  277.  
  278.         SYS_LIBRARIES = -lXpm -L../Xc -lXc
  279.  
  280.   Yes! Here were the missing libraries.
  281.  
  282.   Possibly the linker needed to see the LDLIBS before the LOCAL_LIBS...
  283.   So, the first thing to try was to modify the Makefile by transposing
  284.   the $(LOCAL_LIBS) and $(LDLIBS) on line 495, so it would now read:
  285.  
  286.                $(CCLINK) -o $@ $(LDOPTIONS) $(OBJS) $(LDLIBS) $(LOCAL_LIBS)
  287.        $(EXTRA_LOAD_FLAGS)                          ^^^^^^^^^^^^^^^^^^^^^^^
  288.  
  289.   I tried running make again with the above change, and lo and behold,
  290.   it worked this time. Of course,  Xscrabble still needed some fine
  291.   tuning and twiddling, such as renaming the dictionary and commenting
  292.   out some assert statements in one of the source files, but since then
  293.   it has been providing me with many hours of pleasure.
  294.  
  295.   You may e-mail Matt Chapman <mailto:matt@belgarath.demon.co.uk>, and
  296.   download Xscrabble from his home page
  297.   <http://www.belgarath.demon.co.uk/programs/index.html>.
  298.  
  299.   ______________________________________________________________________
  300.      Scrabble is a registered trademark of the Milton Bradley Co., Inc.
  301.   ______________________________________________________________________
  302.  
  303.   7.  Second Example: Xloadimage
  304.  
  305.   The second example poses an easier problem. The xloadimage program
  306.   seemed a useful addition to my set of graphic tools.  I copied the
  307.   xloadi41.gz file directly from the source directory on the CD included
  308.   with the excellent ``X User Tools'' book, by Mui and Quercia. As
  309.   expected, tar xzvf unarchives the files.  Make, however, produces a
  310.   nasty-looking error and terminates.
  311.  
  312.   ______________________________________________________________________
  313.   gcc -c -O -fstrength-reduce -finline-functions -fforce-mem
  314.   -fforce-addr -DSYSV  -I/usr/X11R6/include
  315.   -DSYSPATHFILE=\"/usr/lib/X11/Xloadimage\" mcidas.c
  316.  
  317.   In file included from /usr/include/stdlib.h:32,
  318.                    from image.h:23,
  319.                    from xloadimage.h:15,
  320.                    from mcidas.c:7:
  321.   /usr/lib/gcc-lib/i486-linux/2.6.3/include/stddef.h:215:
  322.   conflicting types for `wchar_t'
  323.   /usr/X11R6/include/X11/Xlib.h:74: previous declaration of
  324.   `wchar_t'
  325.   make[1]: *** [mcidas.o] Error 1
  326.   make[1]: Leaving directory
  327.   `/home/thegrendel/tst/xloadimage.4.1'
  328.   make: *** [default] Error 2
  329.   ______________________________________________________________________
  330.  
  331.   The error message contains the essential clue.
  332.  
  333.   Looking at the file image.h, line 23...
  334.  
  335.   ______________________________________________________________________
  336.          #include <stdlib.h>
  337.   ______________________________________________________________________
  338.  
  339.   Aha, somewhere in the source for xloadimage, wchar_t has been rede¡
  340.   fined from what was specified in the standard include file, stdlib.h.
  341.   Let us first try commenting out line 23 in image.h, as perhaps the
  342.   stdlib.h include is not, after all, necessary.
  343.  
  344.   At this point, the build proceeds without any fatal errors. The
  345.   xloadimage program functions correctly now.
  346.  
  347.   8.  Final Words
  348.  
  349.   To sum up, persistence makes all the difference  (and a high
  350.   frustration threshold certainly helps). As in all endeavors, learning
  351.   from mistakes is critically important.  Each misstep, every failure
  352.   contributes to the body of knowledge that will lead to mastery of the
  353.   art of building software.
  354.  
  355.   9.  References and Further Reading
  356.  
  357.   BORLAND C++ TOOLS AND UTILITIES GUIDE, Borland International, 1992,
  358.   pp. 9-42.
  359.   [One of the manuals distributed with Borland C++, ver. 3.1. Gives
  360.   a fairly good intro to Make syntax and concepts, using Borland's limited
  361.   implementation thereof.]
  362.  
  363.   DuBois, Paul: SOFTWARE PORTABILITY WITH IMAKE, O'Reilly and Associates,
  364.   1996, ISBN 1-56592-226-3.
  365.   [This is reputed to be the definitive Imake reference, though I did not
  366.   have it available when writing this article.]
  367.  
  368.   Lehey, Greg: PORTING UNIX SOFTWARE, O'Reilly and Associates, 1995, ISBN
  369.   1-56592-126-7.
  370.  
  371.   Mui, Linda and Valerie Quercia: X USER TOOLS, O'Reilly and Associates,
  372.   1994, ISBN 1-56592-019-8, pp. 734-760.
  373.  
  374.   Oram, Andrew and Steve Talbott: MANAGING PROJECTS WITH MAKE, O'Reilly
  375.   and Associates, 1991, ISBN 0-937175-90-0.
  376.  
  377.   Stallman, Richard M. and Roland McGrath: GNU MAKE, Free Software
  378.   Foundation, 1995, ISBN 1-882114-78-7.
  379.  
  380.   Welsh, Matt and Lar Kaufman: RUNNING LINUX, O'Reilly and Associates,
  381.   1995, ISBN 1-56592-100-3, pp. 325-333, 377-379, 381.
  382.   [Still the best overall Linux reference, though lacking in depth
  383.   in some areas.]
  384.  
  385.   And, of course, the man pages for make, imake, xmkmf, and ldconfig.
  386.  
  387.