Chapter 1 : Building and installing free software

I am often asked how to install free software from sources. Compiling software by oneself is really easy because most of the steps to follow are the same whatever the software to install is.

The aim of this document is to guide the beginner step by step, by trying to avoid the pitfall of incantatory, and by explaining to him the meaning of each move. Yet, I assume that the reader has a minimal knowledge of Unix (ls or mkdir for instance).

This guide is only a guide, not a reference manual. That is why several links are given at the end so as to answer the remaining questions. This guide can probably be improved, so I will thanksfully receive remarks or corrections on its contents.

Introduction

What makes the difference between free software and proprietary software is the access to the sources of the software[23]. That means that free software is distributed as archives of source files. It may disconcert beginners, because users of free software must compile sources by themselves before they can use the software.

Nowadays, there are compiled versions of most of the existing free software. The user in a hurry just has to install binaries. Yet, some free software are not distributed under this form, or the earlier versions are not yet distributed under binary form. Furthermore, if you use an exotic operating system or an exotic architecture, a lot of software will not be compiled for you. More, compiling software by oneself allows to keep only the interesting options or to extend the functionalities of the software by adding extensions in order to obtain a software that fits exactly one's needs.

Requirements

To build a free software, you need:

• a computer with a running operating system,
• some space on your disk,
• a compiler (usually for the C language), an archiver (tar),
• general knowledge of the operating system you use,
• some food (in bad cases, it may last a long time). A real hacker eats pizzas, not quiches.
• some drink (for the same reason). A real hacker drinks cola soda (for caffeine).
• the phone number of your techie friend, who recompiles his kernel each week,
• but especially patience (and a lot of it!).

Compiling a free software does not generally present a lot of problems, but if you are not used to it, the smallest snag can throw you into a difficult position. The aim of this document is precisely to show you how to escape from such a situation.

Compilation

Principle

In order to translate a source code into a binary file, a compilation must be done (usually from C or C++ sources, which are the most widespread languages among the (Unix) free software community). Some free software is written in languages which do not require compilation (for instance Perl or the shell, but they still require to be configured.

C compilation is logically done by a C compiler that is usually GCC, the free compiler written by the GNU project (at URL http://www.gnu.org/). Compiling a whole software package is a complex task, which goes through the successive compilation of different source files (it is easier for the programmer to put the different parts of his work in separate files, for various reasons). In order to make it easier, these repetitive operations are made by a utility named make.

The four steps of compilation

To understand how compilation works (and so, to be able to solve possible problems), one has to know its four steps. Its object is to little by little convert a text written in a language that is comprehensible by a trained human being (i.e. C language), towards a language that is comprehensible by a machine (or a very trained human being and even so, in few cases). GCC executes four programs one after the other, each of which takes on one step:

• cpp: the first step consists in replacing directives (preprocessors) by pure C instructions. Typically, that means inserting a header (#include) or defining a macro (#define). At the end of this stage, a pure C code is generated.
• cc1: this step consists in converting C into assembly language. The generated code depends on the target architecture.
• as: this step consists in generating object (or binary) code from the assembly language. At the end of this stage, a .o file is generated.
• ld: the last step (linkage) links all the object files (.o) and the associated libraries, and produces an executable file.

Structure of a distribution

A correctly structured free software distribution always has the same organization:

• an INSTALL file, which describes the installation procedure.
• a README file, which contains general information related to the program (short description, author, URL where to fetch it, related documentation, useful links, etc). If the INSTALL file is missing, the README file usually contains a brief installation procedure.
• a COPYING file, which contains the license or describes the distribution conditions of the software. Sometimes a LICENCE file replaces it.
• a CONTRIB or CREDITS file, which contains a list of people related to the software (active participation, pertinent comments, third-party programs, etc).
• a CHANGES file (or less frequently, a NEWS file), which contains last improvements and bugfixes.
• a Makefile file (see the section 147.0), which allows to compile the software (it is a necessary file for make. This file often does not exist at the beginning and is generated during configuration process.
• quite often, a configure or Imakefile file, which allows one to generate a new file Makefile,
• a directory that contains the sources, and where the binary file is usually stored at the end of the compilation. Its name is often src.
• a directory that contains the documentation related to the program (usually in man or Texinfo format), whose name is often doc.
• sometimes, a directory that contains data specific to the software (typically configuration files, example of produced data, or resources files).

Decompression

tar.gz archive

The standard[24] of compression under Unix systems is the gzip format, developed by the GNU project, and considered as one of the best general compressing tools.

gzip is often associated with a utility named tar. tar is a survivor of antediluvian times, when computerists stored their data on tapes. Nowadays, floppy disks and CDROM have replaced tapes, but tar is still being used to create archives. All the files in a directory can be appended in a single file for instance. This file can then be easily compressed with gzip.

This is the reason why much free software is available as tar archives, compressed with gzip. So, their extensions are .tar.gz (or also .tgz to shorten).

The use of GNU Tar

To decompress this archive, gzip and then tar can be used. But the GNU version of tar (gtar) allows to use gzip "on-the-fly", and to uncompress an archive file without hardly noticing it (and without the need for the extra disk space).

The use of tar is incantatory:

tar <file options> <.tar.gz file> [<files>]

The <files> option is not compulsory. If it is omitted, processing will be made on the whole archive. This argument does not need to be specified to extract the contents of a .tar.gz archive.

For instance:

$ tar xvfz guile-1.3.tar.gz
-rw-r--r-- 442/1002      10555 1998-10-20 07:31 guile-1.3/Makefile.in
-rw-rw-rw- 442/1002       6668 1998-10-20 06:59 guile-1.3/README
-rw-rw-rw- 442/1002       2283 1998-02-01 22:05 guile-1.3/AUTHORS
-rw-rw-rw- 442/1002      17989 1997-05-27 00:36 guile-1.3/COPYING
-rw-rw-rw- 442/1002      28545 1998-10-20 07:05 guile-1.3/ChangeLog
-rw-rw-rw- 442/1002       9364 1997-10-25 08:34 guile-1.3/INSTALL
-rw-rw-rw- 442/1002       1223 1998-10-20 06:34 guile-1.3/Makefile.am
-rw-rw-rw- 442/1002      98432 1998-10-20 07:30 guile-1.3/NEWS
-rw-rw-rw- 442/1002       1388 1998-10-20 06:19 guile-1.3/THANKS
-rw-rw-rw- 442/1002       1151 1998-08-16 21:45 guile-1.3/TODO
...

Among the options of tar:

• v makes tar verbose. That means it displays all the files it finds in the archive on the screen. If this option is omitted, the processing will be silent.
• f is a compulsory option. Without it, tar tries to use a tape instead of an archive file (i.e., the /dev/rmt0 device).
• z allows to treat a "gziped" archive (with a .gz extension). If this option is forgotten, tar will produce an error. Conversely, this option must not be used with an uncompressed archive.
• tar allows to perform several actions on an archive (extract, read, create, add...). An option defines which action is used:
  • x: it allows to extract files from the archive.
  • t: it lists the contents of the archive.
  • c: it allows to create an archive. That implies to destruct its current contents. You may use it to backup your personal files, for instance.
  • c: it allows to add files at the end of the archive. It cannot be used with a compressed archive.

bzip2

A compression format named bzip2 tends to replace gzip. bzip2 produces shortest archives than gzip does, but is not yet a standard. Since little ago, .tar.bz2 extensions can be found.

bzip2 is used like gzip by means of the tar command. The only thing to do is to replace the letter z by the letter y. For instance:

$ tar xvfy foo.tar.bz2

Some distributions use or used to use the option I instead:

$ tar xvfI foo.tar.bz2

Another way (which seems to be more portable, but is longer to type!):

$ tar --use-compress-program=bzip2 -xvf foo.tar.bz2

bzip2 must be installed and included in your 'PATH' environment variable before you run tar.

Just do it!

The easiest way

Now that you are ready to uncompress the archive, do not forget to do it as administrator (root). You will need to do things that a single user is not allowed to do, and even if you can perform some of them as a regular user, it is simpler to just be root the whole time.

The first step is to be in the /usr/local/src directory, and to copy the archive there. Thanks to it, you will always be able to find the archive if you lose the installed software. If you do not have a lot of space on your disk, save the archive on a floppy disk after having installed the software. You can also delete it but be sure that you can find it on the Web whenever you need it.

Normally, decompressing a tar archive should create a new directory (you can check that beforehand thanks to the t option). Go then in that directory, you are now ready to proceed further.

The safest way

Unix systems (of which GNU/Linux et FreeBSD are examples) are secured systems. That means that normal users cannot either make operations that may endanger the system (format a disk, for instance) or alter other users' files. In practice and in particular, it immunizes the system against viruses.

On the other hand, root can do everything, even running a malicious program. To dispose of the source code is a guarantee of security faced to viruses, but you can be paranoiac[25].

The idea is to create a user dedicated to administration (free or admin for example) by using the adduser command. This user must be allowed to write in the following directories: /usr/local/src, /usr/local/bin and /usr/local/lib, as well as all the sub-tree of /usr/man (he also may need to be able to copy files elsewhere). I recommend to you to make this user owner of the necessary directories, or to create a group for him and to make the directories writable for the group.

Once these precautions are taken, you can follow the instructions in the section 84.0.

Configuration

A purely technical interest of the fact you dispose of the sources is the porting of the software. A free software developed for a Unix system can be used on all of the existing Unix systems (whether they are free or proprietary), with however some changes. That requires to configure the software just before compiling it.

Several configuration systems exist, you have to use the one the author of the software wants (sometimes, several are needed). Usually, you can:

• use Autoconf (see the section 105.0) if a file named configure exists in the parent directory of the distribution.
• use Imake (see the section 126.0) if a file named Imakefile exists in the parent directory of the distribution.
• run a shell script (for instance install.sh) according to the contents of the INSTALL file (or the README file)

Autoconf

Principle

Autoconf is used to correctly configure a software. It creates the files required by the compilation (for instance, Makefile for instance), and sometimes changes directly the sources (for instance by using a config.h.in file).

The principle of Autoconf is simple:

• the programmer of the software knows which tests are required to configure his software (eg: "which version of this library do you use?"). He writes them in a file named configure.in, following a precise syntax.
• he executes Autoconf, which generates a configuration script named configure from the configure.in file. This script makes the tests required when the program is configured.
• the final user runs the script, and Autoconf configures all that is needed by the compilation.

Example

An example of the use of Autoconf:

$ ./configure
loading cache ./config.cache
checking for gcc... gcc
checking whether the C compiler (gcc  ) works... yes
checking whether the C compiler (gcc  ) is a cross-compiler... no
checking whether we are using GNU C... yes
checking whether gcc accepts -g... yes
checking for main in -lX11... yes
checking for main in -lXpm... yes
checking for main in -lguile... yes
checking for main in -lm... yes
checking for main in -lncurses... yes
checking how to run the C preprocessor... gcc -E
checking for X... libraries /usr/X11R6/lib, headers /usr/X11R6/include
checking for ANSI C header files... yes
checking for unistd.h... yes
checking for working const... yes
updating cache ./config.cache
creating ./config.status
creating lib/Makefile
creating src/Makefile
creating Makefile

To have a better control of what configure generates, some options may be added by the way of the command line or environment variables. Example:

$ ./configure --with-gcc --prefix=/opt/GNU

or (with Bash):

$ export CC=`which gcc`
$ export CFLAGS=-O2
$ ./configure --with-gcc

or:

$ CC=gcc CFLAGS=-O2 ./configure

What if... it does not work?

Typically, it is an error of type configure: error: Cannot find library guile (most of the errors of the configure script).

That means that the configure script was not able to find a library (the guile library in the example). The principle is that the configure script compiles a short test program, which uses this library. If it does not succeed in compiling this program, it will not be able to compile the software. Then an error occurs.

• Look for the reason of the error by looking at the end of the config.log file, which contains a track of all the steps of the configuration. The C compiler is clear enough with its error messages. That will help you in solving the issue.
• Check that said library is well installed. If not, install it (from the sources or a compiled binary file) and run configure again. An efficient way to check it is to search for the file that contains the symbols of the library, which is always lib<name>.so. For instance,

  $ find / -name 'libguile*'
  

  or else:

  $ locate libguile
  

• Check that it is accessible by the compiler. That means it is in a directory among: /usr/lib, /lib, /usr/X11R6/lib (or among those specified by the environment variable 'LD_LIBRARY_PATH', explained page 189.0. Check that this file is a library by typing file libguile.so.
• Check that the headers corresponding to the library are installed in the right place (usually /usr/include or /usr/local/include or /usr/X11R6/include). If you do not know which headers you need, check that you have installed the development version of the required library (for instance, gtk+-devel instead of libgtk). The development version of the library provides the "include" files necessary for the compilation of a software using this library.
• Check that you have enough space on your disk (the configure script needs some space for temporary files). Use the command df -k to display the partitions of your system, and mind the full or nearly full partitions.

If you do not understand the error message stored in the config.log file, do not hesitate to ask for help from the free software community (see section 231.0).

Furthermore, check whether configure answers by 100% of No or whether it answers No while you are sure that a library exists. For instance, it would be very strange that there is no curses library on your system). In that case, the 'LD_LIBRARY_PATH' variable is probably wrong!

Imake

Imake allows to configure a free software by creating a Makefile file from simple rules. These rules determine which files need to be compiled to build the binary file, and Imake generates the corresponding Makefile. These rules are specified in a file named Imakefile.

What makes the interest of Imake is that it uses information site-dependent (architecture-dependent). It is quite handy for applications using X Window System. But Imake is used for many other applications.

The easiest use of Imake is to go into the main directory of the decompressed archive, and then to run the xmkmf script, which calls the imake program:

$ xmkmf -a
imake -DUseInstalled -I/usr/X11R6/lib/X11/config
make Makefiles

If the site is not correctly installed, recompile and install X11R6!

Various shell scripts

Read the INSTALL or README files for more information. Usually, you have to run a file of type install.sh or configure.sh. Then, either the installation script is non-interactive (and determines itself what it needs) or it asks you information on your system (paths, for instance).

If you do not manage to determine the file you have to run, you can type ./ (under Bash), and than press twice the TAB key (tabulation key). Bash automatically (in its default configuration) completes by a possible executable file from the directory (therefore, a possible configuration script). If several files may be executed, it gives you a list. You just have to choose the right file.

A particular case is the installation of Perl modules (but not only). The installation of such modules is made by the execution of a configuration script, which is written in Perl. The command to execute is usually:

$ perl Makefile.PL

Alternatives

Some free software distributions are badly organized, especially during the first stages of development (but the user is warned!). They sometimes require to change "by hand" some configuration files. Usually, these files are a Makefile file (see section 147.0) and a config.h file (this name is only conventional).

I advise against these manipulations except for users who know what they are doing. This requires a real knowledge and some motivation to succeed. But practice makes perfect.

Compilation

Now that the software is correctly configured, it only remains to be compiled. This stage is usually easy, and does not set serious problems.

make

The favorite tool of the free software community to compile sources is make. It has two interests:

• the developer saves time, because it allows one to efficiently manage compilation of his project,
• final user can compile and install the software in few command lines, even if he has no preliminary knowledge of development.

Actions that must be executed to obtain a compiled version of the sources are stored in a file often named Makefile or GNUMakefile. Actually, when make is called, it reads this file -- if it exists -- in the current directory. If not, the file may be specified by using the option -f with make.

Rules

make operates in accordance with a system of dependencies. So compiling a binary file ("target") requires to go through several stages ("dependencies"). For instance, to create the (imaginary) glloq binary file, the main.o and init.o object files (intermediate files of the compilation) must be compiled and then linked. These object files are also targets, whose dependencies are the source files.

This text is only a minimal introduction to survive in the merciless world of make. If you want to learn more, I advise you to go to website of APRIL (http://www.april.org/groupes/doc/), where you can find more detailed documentation about make. For an exhaustive documentation, refer to Managing Projects with Make, 2nd edition, O'Reilly, by Andrew Oram and Steve Talbott.

Go, go, go!

Usually, the use of make follows several conventions. For instance:

• make without argument just executes the compilation of the program, without installation.
• make install compiles the program (but not always), and provides the installation of the required files at the right place on the file system. Some files are not always correctly installed (man, info), they must be copied by the user himself. Sometimes, make install has to be executed again in sub-directories. Usually, this happens with modules developed by third parties).
• make clean clears all the temporary files created by the compilation, and also the executable file in most cases.

The first stage is to compile the program, and therefore to type (imaginary example):

$ make
gcc -c glloq.c -o glloq.o
gcc -c init.c -o init.o
gcc -c main.c -o main.o
gcc -lgtk -lgdk -lglib -lXext -lX11 -lm glloq.o init.o main.o -o glloq

Excellent, the binary file is correctly compiled. We are ready to go to the next stage, which is the installation of the files of the distribution (binary files, data files, etc). See section 210.0.

Explanations

If you are curious enough to look in the Makefile file, you will find known commands (rm, mv, cp, etc), but also strange strings, looking like '$(CFLAGS)'.

They are variables, that means strings that are usually set at the beginning of the Makefile file, and then replaced by the value they are associated with. It is quite useful when you want to use the same compilation options several times in a row.

For instance, to print the string "foo" on the screen using make all:

TEST = foo
all:
        echo $(TEST)

Most of the time, the following variables are set:

• 'CC': this is the compiler. Usually, it is cc, which is in most of free systems synonymous with gcc. When in doubt, put here gcc.
• 'LD': this is the program used to ensure the final compilation stage (see section 42.0). By default, this is ld.
• 'CFLAGS': these are the additional arguments that are given to the compiler during the first compilation stages. Among them:
  • -I<path>: specifies to the compiler where to search some additional headers (eg: -I/usr/X11R6/include allows to include the headers that are in directory /usr/X11R6/include).
  • -D<symbol>: defines an additional symbol, useful for programs whose compilations depend on the defined symbols (ex: use the string.h file if 'HAVE_STRING_H' is defined).

  There are often compilation lines like:

  $(CC) $(CFLAGS) -c foo.c -o foo.o
  

• 'LDFLAGS' (or 'LFLAGS'): these are arguments used during the last compilation stage. Among them:
  • -L<path>: specifies an additional path where to search for libraries (eg: -L/usr/X11R6/lib).
  • -l<library>: specifies an additional library to use during the last compilation stage.

What if... it does not work?

Do not panic, it can happen to anyone. Among the most common causes:

• glloq.c:16: decl.h: No such file or directory:

  The compiler did not manage to find the corresponding header. Yet, the software configuration step should have anticipated this error. How to solve this problem:

  • check that the header really exists on the disk in one of the following directories: /usr/include, /usr/local/include, /usr/X11R6/include or one of their sub-directories. If not, look for it on the whole disk (with find or locate), and if you still do not find it, check that you have installed the library corresponding to this header. You can find examples of the find and locate commands in their respective manual pages.
  • check that the header is really readable (type less <path>/<file>.h to test this)
  • if it is in a directory like /usr/local/include or /usr/X11R6/include, you have sometimes to add a new argument to the compiler. Open the corresponding Makefile (be careful to open the right file, those in the directory where the compilation fails[26]) with your favorite text editor (Emacs, VI, etc). Look for the faulty line, and add the string -I<path> -- where <path> is the path where the header in question can be found -- just after the call of the compiler (gcc, or sometimes $(CC)). If you do not know where to add this option, add it at the beginning of the file, after CFLAGS=<something> or after CC=<something>.
  • launch make again, and if it still does not work, check that this option (see the previous point) is added during compilation on the faulty line.
  • if it still does not work, call for help from your local guru, buy a new one, or call for help from the free software community to solve your problem (see section 231.0).
• glloq.c:28: `struct foo' undeclared (first use this function):

  The structures are special data types that all programs use. A lot of them are defined by the system in headers. That means that the problem is certainly caused by a lacking or misused header. The correct procedure for solving the problem is:

  • try to check whether the structure in question is defined in the program or by the system. A solution is to use the command grep in order to see whether the structure is defined in one of the headers.

    For instance, when you are in the root of the distribution:

    $ find . -name '*.h'| xargs grep 'struct foo' | less
    

    Many lines may appear on the screen (each time that a function using this type of structure is defined for instance). If it exists, pick out the line where the structure is defined by looking at the header file obtained by the use of grep.

    The definition of a structure is:

    struct foo {
          <contents of the structure>
    };
    

    Check if it corresponds to what you have. If so, that means that the header is not included in the faulty .c file. There are two solutions:

    • add the line #include "<filename>.h" at the beginning of the faulty .c file.
    • or copy-paste the definition of the structure at the beginning of this file (it is not really neat, but at least it usually works).
  • if not, do the same thing with the system header files (which are usually in directories /usr/include, /usr/X11R6/include, or /usr/local/include). But this time, use the line #include <<filename>.h>.
  • if this structure still does not exist, try to find in which library (i.e set of functions put together in a single package) it should be defined (see in the INSTALL or README file which are the libraries used by the program and their required versions). If the version that the program needs is not the one installed on your system, update this library.
  • if it still does not work, check that the program properly works with your architecture (some programs have not been ported yet on all the Unices). Check also that you have correctly configured the program (when configure ran, for instance) for your architecture.
• parse error:

  It is a problem that is quite complicated to solve, because it often is an error that appears at a certain line, but after that the compiler has met it. Sometimes, it is simply a data type that is not defined. If you meet an error message like:

  main.c:1: parse error before `glloq_t
  main.c:1: warning: data definition has no type or storage class
  

  then the problem is that the glloq_t type is not defined. The solution to solve the problem is more or less the same that in the previous problem.

  Note: there may be a parse error in the old curses libraries if my memory serves me right.

• no space left on device:

  The problem is easy to solve: there is not enough space on the disk to generate a binary file from the source file. The solution consists in making free space on the partition that contains the install directory (delete temporary files or sources, uninstall the programs you do not use). If you have uncompressed it in /tmp, rather do that in /usr/local/src, which avoids needlessly saturating the /tmp partition. Check furthermore whether there are core> files on your disk. If so, delete them or make them get deleted if they belong to another user.

• /usr/bin/ld: cannot open -lglloq: No such file or directory:

  That clearly means that the ld program (used by gcc during the last compilation stage) does not manage to find a library. To include a library, ld searches for a file whose name is in the arguments of type -l<library>. This file is lib<library>.so. If ld does not manage to find it, it produces an error message. To solve the problem, follow the steps bellow:

  • Check that the file exists on the hard disk by using the locate command. Usually, the graphic libraries can be found in /usr/X11R6/lib. For instance:

    $ locate libglloq
    

    If it is unrewarding, you can make a search with the find command (eg: find /usr -name libglloq.so*). If you can not find the library, you will have to install it.

  • Once the library is located, check that it is accessible by ld: the /etc/ld.conf file specifies where to find these libraries. Add the incriminate directory at the end (you may have to reboot your computer for this to be taken into account). You also can add this directory by changing the contents of the environment variable 'LD_LIBRARY_PATH'. For instance, if the directory to add is /usr/X11R6/lib, type: export

    LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/X11R6/lib (if your shell is Bash).

  • If it still does not work, check that the incriminate library format is ELF (with the file command). If it is a symbolic link, check that the link is good and does not point at an non-existent file (for instance, with nm libglloq.so). The permissions may be wrong (if you use another account than root and if the library is protected against read for example).
• glloq.c(.text+0x34): undefined reference to `glloq_init':

  It is a matter of a symbol that was not solved during the last compilation stage. Usually, it is a library problem. There may be several causes:

  • the first thing to do is to know whether the symbol is supposed to be in a library. For instance, if it is a symbol beginning by gtk, it belongs to the gtk library. If the name of the library is hardly identifiable (frobnicate_foobar), you may list the symbols of a library with the nm command. For example,

    $ nm libglloq.so
    0000000000109df0 d glloq_message_func
    000000000010a984 b glloq_msg
    0000000000008a58 t glloq_nearest_pow
    0000000000109dd8 d glloq_free_list
    0000000000109cf8 d glloq_mem_chunk
    

    Adding the -o option to nm allows to print the library name on each line, which make the searches easier. Let's imagine that we search for the symbol bulgroz_max, a barbarous solution is to make a search like:

    $ nm /usr/lib/lib*.so | grep bulgroz_max
    $ nm /usr/X11R6/lib/lib*.so | grep bulgroz_max
    $ nm /usr/local/lib/lib*.so | grep bulgroz_max
    /usr/local/lib/libfrobnicate.so:000000000004d848 T bulgroz_max
    

    Wonderful! The symbol bulgroz_max is defined in the frobnicate library (the capital letter T is before its name). Then, you only have to add the string -lfrobnicate in the compilation line by editing the Makefile file: add it at the end of the line where 'LDFLAGS' or 'LFGLAGS' (or 'CC' at worst) are defined, or on the line corresponding at the creation of the final binary file.

  • the compilation is made with a version of the library that is not the one allowed for the software. Read the README or INSTALL files of the distribution to know which version must be used.
  • not all the object files of the distribution are correctly linked. The file where this function is defined is lacking. Type nm -o *.o to know which one it is and add the corresponding .o file on the compilation line if it is missing.
  • the incriminate function or variable is maybe fanciful. Try to delete it: edit the incriminate source file (its name is specified at the beginning of the error message). It is a desperate solution whose consequence will certainly be an anarchic running of the software (segfault at start, etc).
• Segmentation fault (core dumped):

  Sometimes, the compiler hangs lamentably and produces this error message. I have no advise except asking you to install a more recent version of your compiler.

• no space on /tmp

  Compilation needs temporary workspace during the different stages; if it does not have space, it fails. So, you have to clean the partition, but be careful some programs being executed (X server, pipes, etc) can hang if some files are deleted. You must know what you are doing! If /tmp is part of a partition that does not only contain it (for example the root), search and delete some possible core files.

• make/configure in infinite recursion

  It is often a problem of time in your system. Indeed, make needs to know the date in the computer and the date of the files it checks. It compares the dates and uses the result to know whether the target is more recent than the dependence.

  Some date problems may induce make to endlessly build itself (or to build and build again a sub-tree in infinite recursion). In such a case, the use of touch (whose consequence is to put the files in argument at the current time) usually solves the problem.

  For instance:

  $ touch *
  

  Or also (more barbarous, but efficient):

  $ find . | xargs touch
  

Installation

With make

Now that all is compiled, you have to copy the built files to an appropriate place (usually in one of the sub-directories of /usr/local).

make can usually perform this task. A special target is the target install. So, using make install allows to install the required files.

Usually, the procedure is described in the INSTALL or README file. But sometimes, the developer has forgotten to provide one. In that case, you must install everything by yourself.

Copy then:

• the executable files (programs) in the /usr/local/bin directory
• the libraries (lib*.so files) in the /usr/local/lib directory
• the headers (*.h files) in the /usr/local/include directory (be careful not to delete the originals)
• the data files usually go in /usr/local/share. If you do not know the installation procedure, you can try to run the programs without copying the data files, and to put them at the right place when it asks them to you (in an error message like

  Cannot open /usr/local/share/glloq/data.db

  for example).

• the documentation is a little bit aside:
  • the man files are usually put in one of the sub-directories of /usr/local/man. Usually, these files are in troff (or groff) format, and their extension is a figure. Their name is the name of a command (for instance, echo.1). If the figure is n, copy the file in /usr/local/man/man<n>.
  • the info files are put in the directory /usr/info or /usr/local/info

Here you are finished! Congratulations! You now are ready to compile the whole of your operating system.

Problems

If you just have installed a free software, GNU tar for instance, and if, when you execute it, another software is started or it does not work like it did when you tested it directly from the src directory, it is a 'PATH' problem, which finds the programs in a directory before the one where you have installed the new software. Check by executing type -a <program>.

The solution is to put the installation directory higher in the 'PATH' and/or to delete/rename the files that are executed whereas they were not asked to, and/or rename your new programs (into gtar in this example) so that there is no more confusion.

You can also make an alias if the shell allows it (for instance, say that tar means /usr/local/bin/gtar).

Support

Documentation

Several documentation sources:

• HOWTOs, short documentations on precise points (usually far from what we need here, but sometimes useful). See on your disk in /usr/doc/HOWTO (not always, there are sometimes elsewhere; check that out with the command locate HOWTO),
• the manual pages. Type man <command> to get documentation on the command <command>,
• specialized literature. Several big editors begin to publish books about free systems (especially on GNU/Linux). It is often useful if you are a beginner and if you do not understand all the terms of the present documentation.

Technical support

If you have bought an "official" Linux-Mandrake distribution , you can ask the technical support for information on your system. I think that the technical support has other things to do than help all the users to install additional software, but some of them offer a 'x' days-installation help. Perhaps they can spend some time on compilation problems?

You can also rely on help from the free software community:

• newsgroups (on Usenet) comp.os.linux.* answer all the questions about GNU/Linux. Newsgroups matching comp.os.bsd.* deal with BSD systems. There may be other newsgroups dealing with other Unix systems. Remember to read them for some time prior to writing to them.
• several associations or groups of enthusiasts over the free software community offer a voluntary support. The best thing to find the ones closest to the place you live is to check out the lists on specialized websites or to read the concerned newsgroups for a while.
• several IRC channels offer a real time (but blind) assistance by gurus. See for instance the #linux channel on most of the IRC network, or #linuxhelp on IRCNET.
• as a last resort, ask the developer of the software (if he mentioned his name and his email address in a file of the distribution) if you are sure that you have found a bug (that may be due only to your architecture, but after all, free software is supposed to be portable).

How to find free software

To find free software, a lot of links may help you:

• the huge FTP site sunsite.unc.edu or one of its mirrors
• the following websites make a catalog of many free software that can be used on Unix platforms (but one can also find proprietary software on these):
  • http://www.freshmeat.net/ is probably the most complete site,
  • http://www.linux-france.org/ contains a lot of links to software working with GNU/Linux. Most of them work of course with other free Unix platforms,
  • http://www.gnu.org/software/ for an exhaustive list of all of GNU software. Of course, all of them are free and most are licensed under the GPL.
• you can also perform a search with a search engine like http://www.altavista.com/ and make a request like: +<software> +download or "download software".

Acknowledgements

• Proof-reading and disagreeable comments (and in alphabetical order): Sébastien Blondeel, Mathieu Bois, Xavier Renaut, Kamel Sehil,
• Beta-testing: Laurent Bassaler
• English translation: Fanny Drieu

Copyright

Copyright (c) 1999 Benjamin Drieu, association APRIL (which website is http://www.april.org/).

This document is free documentation; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This work is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You will find the GNU General Public License at address http://www.gnu.org/copyleft/gpl.html; you can also get a copy of it by writing to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.