Building and Project Management
Table of Contents
This chapter deals only with compiled projects, such as C++, Java™ or Fortran projects. Projects for scripting languages like Python and PHP work very differently.
You will find here information on:
Summary of Automake Manager containing an initial overall view of Automake Manager,
Automake Manager Operation describing the basics of how to work with Automake Manager,
In the Build systems chapter we have given a rough overview of the build systems commonly in use on UNIX® systems. In the following sections we will look at this in more detail.
There is some confusion about how to name such things. GNU calls them “build systems” when it describes Automake, Autoconf and Libtool. QMake calls itself “a tool to write Makefiles for different compilers and platforms”. In KDE often the term “project management systems” is used. We will use this term in a broader sense to describe the built-in environments in KDevelop which are used to organize and build your projects. In the context of this section, however, we will mostly talk about “automated build systems”.
If you have a simple “Hello World” program, written in C, you can compile and link it using gcc -o hello hello.c and execute it using the command ./hello, so you do not even need a Makefile.
If you have a C application with several modules and header files and you are only going to run it on your own machine (i.e. it is an in-house application), you will only need a simple Makefile, which is fairly easy to write by hand (use info make to find out more).
The complications begin when:
Your source-code, documentation, graphics, sounds, translations, data files, etc. are located in more than one directory,
You have a hierarchy of directories and sub-directories,
You are using libraries that are not part of the traditional UNIX® set, such as the Qt™ Object Library or the KDE Desktop libraries,
You are using a pre-processor to generate some of your source-code, such as Qt's MOC pre-compiler,
You aim to distribute your application worldwide, to people who may not have the same UNIX®/Linux® system, software and hardware as you,
You require an automated Install and Uninstall facility,
You aim to make your application part of the KDE Desktop set.
If you have some or all of the above situations, you probably need a build system. In the example above we used gcc to compile and build the “Hello World” program, but not all C compilers are called “gcc”. So if you distribute your application to someone who is using some other C compiler, your Makefile must somehow use the name of that person's compiler, otherwise your application will fail to compile—and that is just simple example of what can go wrong.
A build system will iron out these differences for you.
It will check that the libraries you need are present on each receiving machine,
will automatically scan all your application directories for files to pre-process, compile or install and
will install the components of your application in the correct receiving directories, making sure that
the directories are created in the receiving machine as required.
In brief, a build system offers safe and secure methods for your application to be compiled and installed correctly on any receiving machine. As we have shown before in the Project Management Systems survey, KDevelop offers three automated build systems and the option of creating your own Makefile, in short (click on the project names to get more information):
Automake projects which use the GNU standard development tools.
QMake projects which use the trolltech QMake project manager.
ANT projects which use the Apache ANT project manager for Java™ development.
Custom projects which require you to maintain your own Makefiles.
One of these four alternatives must be chosen when you create a project and the choice is difficult to change later, so you should give it some thought before you start.
There are several tutorials available on the GNU Build System (Autoconf, Automake and Libtool) of which the Automake Manager makes use.
A short autoconf tutorial written by Christopher W. Curtis available on the KDevelop home page. It concentrates on some basic steps to modify a Makefile.
A more detailed tutorial can be found in a greater set of tutorials on “Developing software with GNU”.
And there is the famous “Goat Book”, titled “Autoconf, Automake, and Libtool”. This is an easily readable, yet concise, introduction in all main aspects of the GNU Autotools.
The Application Wizard will have set up some initial Makefile.am files when you created a New Project of a type that uses the GNU Build System, such as ->->. During development Automake Manager creates any other Makefile.am files for projects that use the GNU Build System and maintains them all, Application Wizard and Automake Manager created alike.
There will be one Makefile.am file in each directory of your project that contains files to be compiled or installed. It will contain your specifications for compiling, building and installing files and a reference to any subdirectories that also have a Makefile.am file and possibly some files to compile, build and install.
Your project's directories and source files may be structured to any depth, or you may prefer a flat project-structure with all subdirectories at the top level.
The aim of the GNU Build System is to produce source-code file structures that can be compiled, built and installed on any UNIX® or Linux® system by using the simple commands:
./configure make make install # Usually as "root".
and can be uninstalled by the command make uninstall (usually as root).
How does this work? Well configure is a script that
works out the details of whatever system it is in, such as what compiler and libraries to use and where they are located, and then
creates recursive Makefile files by filling in the substitutions in the corresponding Makefile.in files.
The Makefile.in are “input” files—templates which provide basic information for the Makefiles to be produced from them by filling in some system dependent information. They are generated by the Automake utility from the Makefile.am files.
The process of going from Makefile.am (.am denotes “Automake” template files) to Makefile files is handled automatically by the KDevelop Project Manager, using the Autoconf utility, M4 macros and other arcana we need not go into here.
So when make runs, it automatically picks up the correct pieces from the current environment, such as compilers and libraries. Similarly, make install puts your application components, such as executables, documentation and data files in the correct places for that environment.
If you distribute your application as a “tarball” (a single compressed file that KDevelop can create for you), it will include the Makefile.in files and the configure script file, so the recipient can compile, build and install your application without having Automake, Autoconf or KDevelop on their machine. The Makefile.am files are also included, just in case the receiver needs to do any source-code modifications.
The rules are rather different if you distribute via a web-based source-code repository such as KDE CVS.
Generates Makefile.am files in subdirectories it knows as “subprojects”.
Updates Makefile.am files as the project structure changes.
Updates Makefile.am files as files are added to or removed from the project.
Accepts definitions of how the various files are to be built or installed and modifies the Makefile.am accordingly.
Accepts parameters used in building or installing (e.g. library names) and ensures that they are used in the required compilation and build steps.
A Makefile.am file has lines containing variable-names followed by an equals sign and a list of files or parameter values. The “variables” have two-part names, such as bin_PROGRAMS, myapp_SOURCES or kdelnk_DATA. The second part is called the primary and represents something from which to build or install. The first part is called the prefix and represents:
A directory in which to do installation (e.g. bin),
A qualifier for the primary (e.g. myapp for SOURCES, indicating that the source files listed after myapp_SOURCES go into building myapp),
A special prefix noinst (short for “no installation”), usually used to list program header files (.h),
Or the special prefix EXTRA, for configuration-dependent stuff.
For more information on Automake and Makefile.am files, look up info Automake.
Basically, Automake Manager creates and updates the variable-names and lists of files or parameters. See the following example of a Makefile.am for a typical application, called myapp.
## Makefile.am for myapp # this is the program that gets installed. its name is used for all # of the other Makefile.am variables bin_PROGRAMS = myapp # set the include path for X, qt and KDE INCLUDES = $(all_includes) # the library search path. myapp_LDFLAGS = $(KDE_RPATH) $(all_libraries) # the libraries to link against. myapp_LDADD = $(LIB_KFILE) $(LIB_KDEPRINT) # which sources should be compiled for myapp myapp_SOURCES = main.cpp myapp.cpp myappview.cpp # these are the headers for your project noinst_HEADERS = myapp.h myappview.h # let automoc handle all of the meta source files (moc) METASOURCES = AUTO KDE_ICON = myapp # this is where the kdelnk file will go kdelnkdir = $(kde_appsdir)/Utilities kdelnk_DATA = myapp.desktop # this is where the XML-GUI resource file goes rcdir = $(kde_datadir)/myapp rc_DATA = myappui.rc AM_CXXFLAGS = -DMY_C++_PREPROCESSOR_OPTION
As you can see, many of the items on the right hand side are symbols of the form $(xxx). These are environment variables which are defined in the actual KDE environment and are substituted with real values when ./configure generates the final Makefile files in the receiving machine.
Also, sometime after you have started with KDevelop, it is a good idea to run the command ./configure --help, which will show you the range of things you can change at build and installation time, such as for a test environment. In particular, the command:
./configure --prefix=/where/you/wish
will re-direct the entire installation to a directory structure of your choice, by changing the internal variable $(prefix) to value /where/you/wish.
