BerndPol IanWadham 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 &automanag; containing an initial overall view of &automanag;, Automake Manager Operation describing the basics of how to work with &automanag;, 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 (&ie; 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 &automanag; 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 &appwizard; 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 C++ KDE Application framework. During development &automanag; creates any other Makefile.am files for projects that use the &GNU; Build System and maintains them all, &appwizard; and &automanag; 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; &promanag;, 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 (⪚ 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 (⪚ bin), A qualifier for the primary (⪚ 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, &automanag; 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. it's 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. In this chapter you will find a basic description of the &automanag; elements and how to use them. This covers: The &automanag; Window describes the basic structure of the &automanag; main window. The Overall View Window describes the elements of the upper subwindow. The Detail View Window describes the elements of the lower subwindow. Navigating in the &automanag; lists some basic operations you can perform in the &automanag;. Popup Menus in the &automanag; describes the windows which will pop up when you select an action in the &automanag;. &automanag; runs in a split window. The top part is called the Overall View and the bottom part is called the Detail View. Between them is a narrow bar that can be dragged with the mouse to adjust the sizes of the views. In IDEAl mode you can also drag the side of the split window to change the width. On top of each view there is a toolbar, the buttons in which will become activated when an element in this view is selected. This provides one way you can access the actions provided for that view element. The other are context menus which pop up on right mouse button click as will be discussed below. In IDEAl mode there are two additional small buttons in the &automanag; window titlebar left hand side – a triangular shaped right arrow, and a dot button. The arrow button is used to close the window. The dot button on the other hand will keep the window open even if another &kdevelop; window has been selected. (Otherwise the &automanag; window will automatically close whenever another window gets the input focus.) The overall view window contains a tree-list of all the directories in your project that contain program files, documentation or data. Each such directory contains a Makefile.am file and is known in &automanag; as a subproject. There are three typical subprojects in a &kde;-based project as shown in the above illustration: src – source-code files for your application, doc – your user manual or Handbook, po – extracts of strings in your source-code files that require translation into other human languages (⪚ window titles, menu names, button labels, dialog box text and messages of various kinds). Note that the doc subproject always has an en subproject, which you can see if you click on the + symbol next to the word doc. That is because the base language of all documentation in &kde; is United States English (en). If your application becomes part of &kde;, the &kde; translation teams may translate your documentation from United States English into other languages and the translations will go into other subprojects, such as de (German) or fr (French). The strings in the po subproject may also be translated and stored in other files in po, thus allowing your application to be operated by people who do not know English. The doc and po subprojects serve different purposes. doc contains documentation like a user manual, po contains translatable text strings of the user interface which is integrated in the source code of this application. The overall view window serves—amongst other things—as a navigation tool. If you select a subproject in the overall view window, the corresponding details will be shown in the detail view window. The detail view contains a tree-list of all the files in the subproject currently selected in the overall view as well as the compilation, build and installation rules for this subproject. Thus the two views together can give you access to all the components of your application and all the information on how to compile, build and install it. The tree-list in the detail view has two levels. The top level consists of so-called &automanag; targets and the next level contains lists of files that go to make up each target. This concept of an &automanag; target differs somewhat from what a Makefile target usually is. In short: The definition of how a set of files is to be compiled, built or installed is known as a target in &automanag;, but as a variable in Automake itself. A target in make is often something quite different, being the parameter of a make command (⪚ make install, make clean). However some Makefile.am variables do represent an underlying sub-target in make. In both the overall and the detail view you can left-click on the + or - next to a subproject or target name to expand or contract the tree view. If you do that with a subproject in the overall view, it shows or hides the subprojects at the next level down (if any). If you do it with a target in the detail view, it shows or hides the list of files that go into that target. Opening a file for Edit If you &LMB; click on a file name in the detail view, the corresponding file opens up in &kdevelop;'s editing window. Activating the &automanag; Toolbar Buttons If you &LMB; click on the name of a subproject in the overall view or target in the detail view, the name is highlighted and some toolbar buttons become active in the top part of that view. It is recommended that you use the right mouse-button and popup menus, rather than the toolbar buttons, because it is then much easier to see and understand what you are doing. Operations on subprojects and targets have far-reaching effects on the structure, compilation, building and installation of your application. Selecting Actions/Popup Menus If you &RMB; click on the name of a subproject, target or file, a menu pops up and you can then select actions to perform on the subproject, target or file, such as add a target to the subproject, add a file to a target or logically remove the selected file from its target. The following sections explain in short terms which operations the menus make available which will pop up on right mouse button clicks in the &automanag; window. They are meant for overall view only. You will find detailed descriptions of most operations in a later chapter. When you &RMB; click on a file name in the detail view the following menu will pop up allowing you to select one of several operations to be performed on that file. In the illustration below the hi-16app-myapp.png icon file was selected from the Icon data in myapp target of the myapp/src subproject. The main popup-menu item for a file is to Remove the file from its target (&ie; it will no longer be used to compile, build or install that target). The CVS item offers a variety of CVS operations on the file. The Open With item allows you to open the file with a variety of editors or with any application at all (⪚ you can open the icon file in our example with KIcon). The Perforce item is used for similar operations as in CVS using the commercial Perforce version control system. When you right-click on a target in the detail view the following menu will pop up allowing you to select one of several operations to be performed on it. In the illustration below the myapp (Program in bin) target of the myapp/src subproject was selected. The Options item for a target only applies to source code files. In the corresponding dialog box you can specify linker flags and paths on which to locate libraries and you can give a list of actual libraries to be linked in to your application. The Create New File item brings up a dialog in which you can set the file name and the type of file to be generated (from a drop-down list). The Add Existing Files item brings up a dialog box in which you can add an already existing file to this target. The Remove item for a target allows you to logically remove the target and all its files from the project structure. The Make Target Active item only applies to targets containing source code files. New files will always be added to such an active target. The Build Target item calls all necessary compile and make operations to build the code for this target only. When you &RMB; click on a subproject in the overall view window the following menu will pop up which allows you to make major changes to the structure of your project and the way it is compiled, built and installed. You can use it to expand or modify the basic project structure that the &appwizard; has created. The Options item for a subproject controls the way that the subproject will be compiled, built and installed. The dialog box that pops up has tabs for Compiler, Includes, Prefixes and Build Order. The Add Subproject item creates a new directory and skeleton Makefile.am file. The Add Target item pops up a dialog in which you can set the rules for compiling, building or installing a group of files within your subproject. Add Service (... to be written ...) Add Application (... to be written ...) Add Existing Subprojects (... to be written ...) The Remove Subproject item in the popup menu for a subproject is the proper way to remove a subproject. It will adjust the Makefile.am files accordingly. You will also be offered the option to delete all the files (or links) in the corresponding subdirectory. Obviously, this feature should be used with caution. The Build item calls all necessary compile and make operations to build the code for this subproject only. Force Reedit (... to be written ...) Clean (... to be written ...) Install (... to be written ...) Install (as root user) (... to be written ...) autoproject &automake; &autoconf; &libtool; (... to be written ...) configure script config.status script Makefile.in config.h.in Makefile.in into Makefile prefix = @prefix@ INSTALL = @INSTALL@ build_triplet = @build@ CXX = @CXX@ prefix = /home/bernd/kde3 INSTALL = /usr/bin/ginstall -c -p build_triplet = i686-pc-linux-gnu CXX = g++ config.h.in into config.h /* Define if you have libz */ #undef HAVE_LIBZ /* The size of a `int', as computed by sizeof. */ #undef SIZEOF_INT /* Define if you have libz */ #define HAVE_LIBZ 1 /* The size of a `int', as computed by sizeof. */ #define SIZEOF_INT 4 (... to be written ...)

-rpath PIC static plugins: no-undefined Makefile build.xml (... to be written ...) (... to be written ...) (... to be written ...)