While some H/FOSS software is available as binary (executable) packages, much of it is available only in source code form, and requires that you build it yourself before you can run it. Even when binary packages are available, if you are going to contribute to the project by modifying, extending or patch the code, you'll need to get the source code and be able to build the executables yourself.

The tutorial below will introduce you to the two most common build tools used H/FOSS projects, configure and make. It will also walk you through the use of these tools in a small HelloWorld project. In this activity you will install a full-scale FOSS project that uses configure and make. This will obviously require that you use configure and make, but will also require you to, as is quite typical, find and install some additional dependencies and deal with imperfect installation instructions.

Prerequisites

Before starting work through the tutorial below. The Hello World example will introduce you to the use of the unix autotools and the configure and make tools:

• The magic behind configure, make, make install by George Brocklehurst.

Assignment

Your task is to download, configure, build and install Freeciv - "a Free and Open Source empire-building strategy game inspired by the history of human civilization." You should do this in Ubuntu within VirtualBox. Ideally, begin from the last snapshot you created during the Software Installation Activity.

The following broad steps will help to guide you through the process. However, at each step you may need to consult the project installation directions, install unmet dependencies, debug errors and Google to find additional information.

Download / Unpack

Rather than installing the latest version of Freeciv, we will be installing an older version. By installing an older version we'll know where the complications arise and can ensure that the process clearly illustrates the configure/make process. You should feel free to have a go at installing the newest version later if you are interested.

1. Find the freeciv-2.1.9.tar.bz2 file in the Files area of the freeciv SourceForge site. This was available as of this writing (Sept 2016).

2. Download the file by right clicking the link and choosing "Save Link As..." Or if you just click the link, use the "Save File" option.

3. Move the freeciv-2.1.9.tar.bz2 file from your Downloads directory to your Documents directory. Despite the convenience, it is generally poor form to use files or do work in the Downloads directory.

4. Unpack the freeciv-2.1.9.tar.bz2 file to get the freeciv-2.1.9 source directory. tar
   Tips:
   • File with the extension bz2 are compressed archive files. You'll need to decompress the bz2 file to get the freeciv-2.1.9.tar file.
   • Files with the extension tar are tape archives. This is a bunch of files and directories packed into a single uncompressed file. You'll need to extract the tape archive to get the freciv-2.1.9 directory that contains the source code.

README and INSTALL

Most H/FOSS project will include README and INSTALL files in their source directory. These files contain information about the product and how to build/install it. The important information necessary to build Freciv is contained the INSTALL file.

1. Open (gedit) or display (more) the INSTALL file.

2. There is a lot of detailed information in this file. If you want to customize the build, or run into problems with the build it may be essential to read it in detail. Fortunately, the build process for many unix based H/FOSS projects is well standardized and you can usually skip over much of this information.

3. For now just skim over the information to get a feel for what type of information is here. Stop when you reach section "2b. Generating the Makefile for the release versions:" and go onto the next section of this activity.

Configure

You learned a lot about configure scripts in the assigned tutorial. They are used by many H/FOSS projects to detect machine particulars and to create the makefiles that are used to control the compilation of the source code into the executable(s).

1. List the contents of the freeciv-2.1.9 directory and notice that it contains the configure.ac and Makefile.am files that get converted in to the configure script and the Makefile.in file by the autotools (autoconf and automake) that you learned about.

2. Also notice that this directory already contains the configure script and the Makefile.in file. This is because autotools were run by the developers and the results were packaged in the tar file you downloaded - how convenient! If they were not, the autotools could be used to generate them from the configure.ac and Makefile.am files. In fact, the developers provide a shell script (autogen.sh) that does exactly that.

3. Run the configure script as described in section "2b. Generating the Makefile for release versions" of the INSTALL document.

4. Bummer... the configure script terminates with an error:
   configure: error: no acceptable C compiler found in $PATH

5. Install the gcc compiler.

6. Bummer... the configure script terminates with an error:
   configure: error: Could not find zlib library.

7. Install the zlib library.
   Tips:
   • Don't try the first thing you find. Search around until something seems reasonable... In this case, the necessary library can be installed with apt-get, so search around until you find something that uses apt-get.
   • Many packages have two versions. One that is used by the executables and one that is needed for development (i.e. when compiling from source). The development package always has the same name as the base package with -dev appended. The basic package should already be installed, so you'll just need to install the -dev package.

8. Run the configure script again.

9. Bummer... the configure script terminates with an error:
   configure: error: could not guess which client to compile

10. This problem is caused because another necessary library is not installed. Had we paid closer attention to all that information in INSTALL we may have caught it before now. But, truth be told, the more common approach is to just plow ahead and address issues as they arise, as we've been doing.

11. Scroll back up through the output of the configure script to find the source of the problem.

12. Install the necessary pkg-config and gtk packages.

13. Run the configure script again.

14. Verify that the freeciv-2.1.9 directory now contains a Makefile.

15. Let out a little whoop of joy! Note that it is quite common to have to repeat the configure process a number of times before you have all of the necessary dependencies installed.

Make

Once the project is configured and the Makefiles have been generated the executable programs must still be built. The make command uses the information from the Makefiles to compile the source code into the executable programs.

1. Compile Freeciv as described in section "3. Compiling Freeciv" of the INSTALL document.

2. Bummer... the make terminates with an error
   make[1]: Leaving directory '/home/comp491/Documents/freeciv-2.1.9'
Makefile:517: recipe for target 'all' failed
make: *** [all] Error 2

3. If you scroll back up through the output of the make command you'll find that the source of the problem is an undefined reference to a symbol in the GLIC library that was discovered during while linking the compiled files:
   /usr/bin/ld: civclient.o: undefined reference to symbol 'pow@@GLIBC_2.2.5'
//lib/x86_64-linux-gnu/libm.so.6: error adding symbols: DSO missing from command line
collect2: error: ld returned 1 exit status
...

4. Use Google to see if anyone has had and solved this issue before.
   Tips:
   • Googling exact error messages is often very effective.
   • Place text in quotes ("blah blah") to search for exact matches.
   • Start with error messages that contain application specific information (e.g. "... civclient.o ...").
   • Return the favor! If you sometime figure out a solution to a problem, be a good FOSS citizen and post your solution.

5. Use the information you find to fix the problem.
   Tips:
   • You'll have to rerun configure with some additional flags.
   • Then you'll have to run make again.

6. List the files in the freeciv-2.1.9 directory and confirm that two new executable files (civ and ser) have been created.

Install

It is possible to run the newly created executable programs directly from the freeciv-2.1.9 directory. However, those files are only available to your user. There are typically many users on a unix based system (e.g. consider the lab machines). To make the executables available to all users they must be placed into a publicly accessible location. On unix systems, this typically means copying them into the /usr/bin or /usr/local/bin directories. Most Makefiles contain instructions for installing the program in an appropriate publicly accessible location.

1. Install Freeciv as described in section "4. Installation" of the INSTALL document.

2. Bummer... make install terminates with an error

3. Examine the output of the make install command to determine the problem.

4. Reissue the make install command correctly.

5. Verify that Freeciv was installed by looking at the files in /usr/local/bin. Notice that the install process changed the names of the executables (civclient and civserver).

Run

When executable programs are installed in a publicly accessible location they are easy for everyone to run from the command line. When the location of the executable is also in the user's PATH environment variable, they simply type the name of the executable on the command line. The shell searches the directories in the PATH for the program and runs it if it is found.

1. Verify that the /usr/local/bin directory is in your PATH environment variable.
   Tips:
   • The env command will list all of your environment variables.
   • Piping that output to grep ^PATH will show just your PATH variable.

2. Run the Freeciv client program (civclient)

3. Don't play long, there's more work to be done and you can play later!

Clean

You may have noticed earlier that the second time you ran make it went much faster than the first. This is because many of the files had already been compiled, had not changed, and were not affected by the new configuration. Sometimes however, you will want to rebuild the entire project from a fresh state. Most Makefiles contain instructions for removing all of the files created by the build process.

1. Run make again. Notice that it goes very quickly because there are no files that need to be compiled.

2. Look at the files in the client and common and server directories. You will see lots of .o files. These are the .c files compiled into object code, which are then linked together into the full executable.

3. Run make clean

4. Look again at the files in the client and common and server directories. Notice that the .o files are now all gone. Running make again would require that they all be compiled again, resulting the much longer process we experienced earlier.

Acknowledgements: This assignment builds from and adapts ideas and content from the following activities created by others:

• http://foss2serve.org/index.php/Test_Installation_Instructions
• http://foss2serve.org/index.php/Building_a_GnomeMusic_Clone
• http://foss2serve.org/index.php/Introduction_to_building_open_source_software
• https://quaid.fedorapeople.org/TOS/Practical_Open_Source_Software_Exploration/html/ch-Building_the_Code.html