Session 7: Compiling Programs

Compiling programs

In the session6 directory, you will notice a number of files:

$ cd ~/session6
$ ls
Makefile         hello.c    hello.f    python_example.py
bash_example.sh  hello.cpp  hello.f90

We’ve already seen some of these (bash_example.sh and python_example.py); we’ll now investigate the hello files. These implement the archetypal “Hello world” program in a variety of languages prevalent within high-performance computing:

• hello.c – written in the C programming language
• hello.cpp – written in the C++ programming language
• hello.f – written in the Fortran-77 programming language
• hello.f90 – written in the Fortran-90 programming language

Open the file written in your preferred programming language. If you have no preference among these, open the C++ version:

$ gedit hello.cpp &

Depending on your language of choice, you should see something similar to the following

// Daniel R. Reynolds
// SMU HPC Workshop
// 20 May 2013

// Inclusions
#include <iostream>

// Example "hello world" routine
int main() {

  // print message to stdout
  std::cout << "Hello World!\n";

  return 0;
}

For those of you familiar to the “Windows” (and even OS X’s “Xcode”) approach to programming, you’re probably more used to seeing this within an Integrated Development Environment (IDE), where you enter your code and click icons that will handle compilation and execution of your program for you. While IDEs exist in the Linux world, they are rarely used in high-performance computing since the compilation approach on your laptop typically cannot create code that will execute on the worker nodes of a cluster.

So with portability in mind, let’s investigate the (rather simple) world of command-line compilation in Linux.

The first step in compilation is knowing which compiler to use. Nearly every Linux system is installed with the GNU compiler collection, GCC:

• gcc – the GNU C compiler
• g++ – the GNU C++ compiler
• gfortran – the GNU Fortran compiler (handles F77/F90/F95/F2003)

However, if you have a very old version of the GNU compiler suite, instead of gfortran you may have g77, that only works with F77 code (no F90 or newer).

The GNU compiler suite is open-source (i.e. you can modify it if you want), free, and is available for all major computer architectures (even Windows); however, it does not always produce the most efficient code. As a result, the SMU Center for Scientific Computation has purchased the PGI compiler suite:

• pgcc - the PGI C compiler
• pgc++ - the PGI C++ compiler
• pgfortran - the PGI Fortran compiler (handles F77/F90/F95/F2003)

In my experience, with some applications a program compiled with the PGI compilers can run 50% faster than the same code compiled with the GNU compilers. We’ll discuss how to use the PGI compiler on ManeFrame II in session 3 later on.

To compile an executable, we merely call the relevant compiler, followed by the files we wish to compile, e.g. for the C code we’d use

$ gcc hello.c

or for the F77 code we’d use

$ gfortran hello.f

Either of these commands will produce a new file named a.out. This is the standard output name for executables produced by compilers. However, since a computer where every program was named “a.out” would be unusable, it is typical to give your your program a somewhat more descriptive name. This is handled with the command line option -o, e.g.

$ g++ hello.cpp -o hello.exe

Compile the program in the language of your choice, naming the executable hello.exe. Once this has been compiled, you can run it just like any other Linux program, via

$ ./hello.exe

$ ls -l hello.exe
-rwxr-xr-x 1 rkalescky math 8166 May 29 12:26 hello.exe

$ file hello.exe
hello.exe: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.18, not stripped

For those who would like additional information on learning computing languages, I’d recommend that you pursue some of the following links, and look through some of the provided code for this workshop (especially in some of the following sessions). The best ways to learn a new language are through following examples and practicing; if you’d like some programming “homework” for practice, ask me after class. Also, Google is a great resource if you’re ever in trouble when programming, since the odds are good that someone else has had the same questions as you, which have been answered on public forums. Just describe your question and do a web search.

Fortran resources:

• Fortran short-course
• Interactive Fortran 90 Programming Course
• Fortran 90 Tutorial

C++ resources:

• C++ By Example: A Hands-On Course in C++
• C++ Language Tutorial
• Interactive C++ Tutorial (focuses on object-oriented programming)

Compiling “typical” Linux packages

As the number of UNIX variants increased, it became harder to write programs which would be portable to all variants. Developers frequently did not have access to every system, and the characteristics of some systems changed from version to version. The GNU configure and build system simplifies the building of programs distributed as source code. All programs are built using a simple, standardized, two step process. The program builder need not install any special tools in order to build the program.

The configure shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses those values to create a Makefile in each directory of the package.

For packages that use this approach, the simplest way to compile a package is:

1. cd to the directory containing the package’s source code.
2. Type ./configure to configure the package for your system.
3. Type make to compile the package.
4. Optionally, type make check to run any self-tests that come with the package.
5. Type make install to install the programs and any data files and documentation.
6. Optionally, type make clean to remove the program binaries and object files from the source code directory.

The configure utility supports a wide variety of options. You can usually use the --help option to get a list of interesting options for a particular configure script.

The only generic option you are likely to use at first is the --prefix option. The directory named by this option will hold machine independent files such as documentation, data and configuration files.

$ mkdir download

$ cd download
$ wget http://faculty.smu.edu/reynolds/unixtut/units-1.74.tar.gz

$ ls

$ gunzip units-1.74.tar.gz

$ tar -xvf units-1.74.tar

$ tar -zxvf units-1.74.tar.gz

$ ls -l
$ cd units-1.74

$ less README

$ ./configure --prefix=$HOME/units-1.7.4

$ echo $HOME

$ make

$ make check

$ make install

$ cd

$ units

$ ./units-1.7.4/bin/units

$ cd ~/units-1.7.4

$ cd bin

$ ./units

You have: 6 feet
You want: meters

        * 1.8288
        / 0.54680665

$ info --file=units.info

$ rm -rf ~/units-1.7.4

How can a Makefile help?

While you may find it to be quite enjoyable to compile every source file by hand, and then manually link them together into an executable, the process can be completely automated by using a Makefile.

A few rules about Makefiles:

• The make program will look for any of the files: GNUmakefile, makefile, and Makefile (in that order) for build instructions. Most people consider the name Makefile as best practice, though any are acceptable.

• Inside the Makefile, lines beginning with the # character are treated as comments, and are ignored.

• Blank lines are ignored.

• You specify a target for make to build using the syntax,

  target : dependencies
        build command 1
        build command 2
        build command 3
  

  where each of the lines following the target : line must begin with a [Tab] character. Each of these lines are executed when make is called. These lines are executed as if they were typed directly at the command line (as with a shell script).

• More than one target may be included in any Makefile.

• If you just type make at the command line, only the first target is run.

As an example, examine the Makefile from session 2. Here, all of the lines are either blank or are comment lines except for the four sets:

hello_cpp.exe : hello.cpp
        g++ hello.cpp -o hello_cpp.exe

hello_c.exe : hello.c
        gcc hello.c -o hello_c.exe

hello_f90.exe : hello.f90
        gfortran hello.f90 -o hello_f90.exe

hello_f77.exe : hello.f
        gfortran hello.f -o hello_f77.exe

Here, we have four build targets, hello_cpp.exe, hello_c.exe, hello_f90.exe and hello_f77.exe (it is traditional to give the target the same name as the output of the build commands).

Each of these targets depend a source code file listed to the right of the colon; here these are hello.cpp, hello.c, hello.f90 and hello.f, respectively.

The indented lines (each require a single [Tab] character) under each target contain the instructions on how to build that executable. For example, make will build hello_cpp.exe by issuing the command g++ hello.cpp -o hello_cpp.exe, which does the compilation, assembly and linking all in one step (since there is only one source code file).

Alternatively, this Makefile could have been written:

hello_cpp.exe : hello.cpp
        g++ -c hello.cpp
        g++ hello.o -o hello_cpp.exe

hello_c.exe : hello.c
        gcc -c hello.c
        gcc hello.o -o hello_c.exe

hello_f90.exe : hello.f90
        gfortran -c hello.f90
        gfortran hello.o -o hello_f90.exe

hello_f77.exe : hello.f
        gfortran -c hello.f
        gfortran hello.o -o hello_f77.exe

or even as

hello_cpp.exe :
        g++ hello.cpp -o hello_cpp.exe

hello_c.exe :
        gcc hello.c -o hello_c.exe

hello_f90.exe :
        gfortran hello.f90 -o hello_f90.exe

hello_f77.exe :
        gfortran hello.f -o hello_f77.exe

(which ignores the dependency on the source code files hello.cpp, hello.c, hello.f90 and hello.f, respectively).

Makefile variables

As you likely noticed, many of the above commands seemed very repetitive (e.g. continually calling gfortran, or repeating the dependencies and target name in the compile line).

As with anything in Linux, we’d prefer to do things as easily as possible, which is where Makefile variables come into the picture. We can define our own variable in a Makefile by placing the variable to the left of an equal sign, with the value to the right (as with Bash):

VAR = value

The main difference with Bash comes in how we use these variables. Again, it requires a $, but we also need to use parentheses or braces, $(VAR) or ${VAR}. In addition, there are a few built-in variables within Makefile commands that can be quite handy:

• $^ – in a compilation recipe, this references all of the dependencies for the target
• $< – in a compilation recipe, this references the first dependency for the target
• $@ – in a compilation recipe, this references the target name

With these, we can streamline our previous Makefile example considerably:

CC=gcc
CXX=g++
FC=gfortran

hello_cpp.exe : hello.cpp
        $(CXX) $^ -o $@

hello_c.exe : hello.c
        $(CC) $^ -o $@

hello_f90.exe : hello.f90
        $(FC) $^ -o $@

hello_f77.exe : hello.f
        $(FC) $^ -o $@

Advanced usage

If we have one main routine in the file driver.c that uses functions residing in multiple input files, e.g. func1.c, func2.c, func3.c and func4.c, it is standard to compile each of the input functions into .o files separately, and then to link them together with the driver at the last stage. This can be very helpful when developing/debugging code, since if you only change one line in file2.c, you do not need to re-compile all of your input functions, just the one that you changed. By setting up your Makefile so that the targets are the .o files, and if the Makefile knows how to build each .o file so that it depends on the respective .c file, recompilation of your project can be very efficient. For example,

CC=gcc

driver.exe : driver.o func1.o func2.o func3.o func4.o
        $(CC) $^ -o $@

driver.o : driver.c
        $(CC) -c $^ -o $@

func1.o : func1.c
        $(CC) -c $^ -o $@

func2.o : func2.c
        $(CC) -c $^ -o $@

func3.o : func3.c
        $(CC) -c $^ -o $@

func4.o : func4.c
        $(CC) -c $^ -o $@

However, if this actually depends on a large number of input functions, the Makefile can become very long if you have to specify the recipe for compiling each .c file into a .o file. To this end, we can supply an explicit rule for how to perform this conversion, e.g.

CC=gcc
OBJS=driver.o func1.o func2.o func3.o func4.o func5.o \
     func6.o func7.o func8.o func9.o func10.o func11.o \
     func12.o func13.o func14.o func15.o

driver.exe : $(OBJS)
        $(CC) $^ -o $@

%.o : %.c
        $(CC) -c $^ -o $@

Here, the last block specifies the rule for how to convert any .c file into a .o file. Similarly, we have defined the OBJS variable to list out all of the .o files that we need to generate our executable. Notice that the line continuation character is \:

• The \ must be the last character on the line (no trailing spaces)
• Continued lines must use spaces to start the line (no “Tab”), though they aren’t required to line up as pretty as in this example.

As a final example, let’s now suppose that all of the files in our project #include the same header file, head.h. Of course, if we change even a single line in this header file, we’ll need to recompile all of our .c files, so we need to add head.h as a dependency for processing our .c files into .o files:

CC=gcc
OBJS=driver.o func1.o func2.o func3.o func4.o func5.o \
     func6.o func7.o func8.o func9.o func10.o func11.o \
     func12.o func13.o func14.o func15.o

driver.exe : $(OBJS)
        $(CC) $^ -o $@

%.o : %.c head.h
        $(CC) -c $< -o $@

Note that to the right of the colon in our explicit rule we have now listed the header file, head.h. Also notice that within the explicit rule, we now use the $< instead of the $^, this is because we want the compilation line to be, e.g.

gcc -c func3.c -o func3.o

and not

gcc -c func3.c head.h -o func3.o

so we only wanted to automatically list the first dependency from the list, and not all dependencies.

Makefile exercise

Create a Makefile to compile the executable driver.exe for this workshop session, out of the files driver.cpp, one_norm.cpp, vector_difference.cpp, vector_product.cpp and vector_sum.cpp. This should encode all of the commands that we earlier needed to do by hand. Start out with the command

$ gedit Makefile &

to have gedit create the file Makefile in the background, so that while you edit the Makefile you can still use the terminal window to try out make as you add commands.

As with the example from session 6, you can incorporate more than one target into your Makefile. The first target in the file will be executed by a make command without any arguments. All other targets may be executed through the command make target, where target is the name you have specified for a target in the Makefile.

For example, a standard Makefile target is to clean up the temporary files created during compilation of the executable, typically entitled clean. In our compilation process, we created the temporary files driver.o, one_norm.o, vector_product.o, vector_sum.o and vector_difference.o. These could be cleaned up with the single command make clean if we add the following lines to the Makefile, after your commands to create driver.exe:

clean :
      rm -f *.o

Now type make clean in the terminal – all of the temporary build files have been removed.

Makefiles can be much more complicated than those outlined here, but for our needs in this tutorial these commands should suffice. For additional information on the make system, see the PDF manual listed below.

Make resources:

• GNU Make manual