path: root/doc/kdevelop/project-management.docbook

<chapter id="project-management">

<chapterinfo>
  <authorgroup>
    <author><firstname>Bernd</firstname><surname>Pol</surname></author>
    <author><firstname>Ian</firstname><surname>Wadham</surname></author>
    <!-- ROLES_OF_TRANSLATORS -->
  </authorgroup>
</chapterinfo>

<title>Building and Project Management</title>

<para>
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.
</para>

<para>
You will find here information on:</para>
<itemizedlist>
  <listitem><para>
  <link linkend="automake-manager-summary">Summary of &automanag;</link> containing an initial overall view of &automanag;,
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation">Automake Manager Operation</link> describing the basics of how to work with &automanag;,
  </para></listitem>
</itemizedlist>

<sect1 id="automake-manager-summary">
<title>Summary of &automanag;</title>

<para>
In the <link linkend="unixdev-buildsystems">Build systems</link> 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.
</para>
<para>
There is some confusion about how to name such things. &GNU; calls them <quote>build systems</quote> when it describes Automake, Autoconf and Libtool. QMake calls itself <quote>a tool to write Makefiles for different compilers and platforms</quote>. In &kde; often the term <quote>project management systems</quote> 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 <quote>automated build systems</quote>.
</para>

<sect2 id="automake-manager-summary-buildsys">
<title>The Need for an Automated Build System</title>

<para>
If you have a simple <quote>Hello World</quote> program, written in C, you can compile and link it using &gcc; <parameter>-o hello hello.c</parameter> and execute it using the command <command>./hello</command>, so you do not even need a <filename>Makefile</filename>.
</para>
<para>
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 <filename>Makefile</filename>, which is fairly easy to write by hand (use <userinput>info make</userinput> to find out more).
</para>
<para>
The complications begin when:
</para>
<itemizedlist>
  <listitem><para>
  Your source-code, documentation, graphics, sounds, translations, data files, &etc; are located in more than one directory,
  </para></listitem>
  <listitem><para>
  You have a hierarchy of directories and sub-directories,
  </para></listitem>
  <listitem><para>
  You are using libraries that are not part of the traditional &UNIX; set, such as the &Qt; Object Library or the &kde; Desktop libraries,
  </para></listitem>
  <listitem><para>
  You are using a pre-processor to generate some of your source-code, such as Qt's MOC pre-compiler,
  </para></listitem>
  <listitem><para>
  You aim to distribute your application worldwide, to people who may not have the same &UNIX;/&Linux; system, software and hardware as you,
  </para></listitem>
  <listitem><para>
  You require an automated Install and Uninstall facility,
  </para></listitem>
  <listitem><para>
  You aim to make your application part of the &kde; Desktop set.
  </para></listitem>
</itemizedlist>

<para>
If you have some or all of the above situations, you probably need a <emphasis>build system</emphasis>. In the example above we used &gcc; to compile and build the <quote>Hello World</quote> program, but not all C compilers are called <quote>&gcc;</quote>. 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&mdash;and that is just simple example of what can go wrong.
</para>
<para>
A build system will iron out these differences for you.
</para>
<itemizedlist>
  <listitem><para>
  It will check that the libraries you need are present on each receiving machine,
  </para></listitem>
  <listitem><para>
  will automatically scan all your application directories for files to pre-process, compile or install and
  </para></listitem>
  <listitem><para>
  will install the components of your application in the correct receiving directories, making sure that
  </para></listitem>
  <listitem><para>
  the directories are created in the receiving machine as required.
  </para></listitem>
</itemizedlist>

<para>
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 <link linkend="makesystems">Project Management Systems</link> 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):
</para>
<itemizedlist>
  <listitem><para>
  <link linkend="automake-project">Automake projects</link> which use the &GNU; standard development tools.
  </para></listitem>
  <listitem><para>
  <link linkend="qmake-project">QMake projects</link> which use the trolltech QMake project manager.
  </para></listitem>
  <listitem><para>
  <link linkend="ant-project">ANT projects</link> which use the Apache ANT project manager for &Java; development.
  </para></listitem>
  <listitem><para>
  <link linkend="custom-project">Custom projects</link> which require you to maintain your own <filename>Makefiles</filename>.
  </para></listitem>
</itemizedlist>

<important>
<para>
One of these four alternatives must be chosen when you create a project and <emphasis>the choice is difficult to change later</emphasis>, so you should give it some thought before you start.
</para>
</important>

</sect2> <!--  automake-manager-summary-buildsys -->

<sect2 id="automake-references">
<title>Tutorials on Autoconf/Automake/Libtool</title>
<para>
There are several tutorials available on the &GNU; Build System (<command>Autoconf</command>, <command>Automake</command> and <command>Libtool</command>) of which the &automanag; makes use.
</para>
<itemizedlist>
  <listitem><para>A short <ulink url="http://www.kdevelop.org/index.html?filename=tutorial_autoconf.html">autoconf tutorial</ulink> written by Christopher W. Curtis available on the &kdevelop; home page. It concentrates on some basic steps to modify a <filename>Makefile</filename>.
  </para></listitem>
  <listitem><para>
  A more detailed tutorial can be found in a greater set of tutorials on  <ulink url="http://www.amath.washington.edu/~lf/tutorials/autoconf/toolsmanual_toc.html"><quote>Developing software with GNU</quote></ulink>.
  </para></listitem>
  <listitem><para>
  And there is the famous <ulink url="http://sources.redhat.com/autobook"><quote>Goat Book</quote></ulink>, titled <quote>Autoconf, Automake, and Libtool</quote>. This is an easily readable, yet concise, introduction in all main aspects of the &GNU; Autotools.
  </para></listitem>
</itemizedlist>

</sect2> <!--  automake-references -->

<sect2 id="automake-manager-basics">
<title>What does &automanag; Do?</title>

<para>
The <link linkend="applicationwizard">&appwizard;</link> will have set up some initial <filename>Makefile.am</filename> files when you created a <guilabel>New Project</guilabel> of a type that uses the &GNU; Build System, such as <menuchoice><guimenuitem>C++</guimenuitem> <guimenuitem>KDE</guimenuitem> <guimenuitem>Application framework</guimenuitem></menuchoice>. During development &automanag; creates any other <filename>Makefile.am</filename> files for projects that use the &GNU; Build System and maintains them all, &appwizard; and &automanag; created alike.
</para>
<para>
There will be one <filename>Makefile.am</filename> 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 <filename>Makefile.am</filename> file and possibly some files to compile, build and install.
</para>

<note><para>
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.
</para></note>

<para>
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:
</para>

<screen>
./configure
make
make install    # Usually as "root".
</screen>

<para>and can be uninstalled by the command <command>make uninstall</command> (usually as root).
</para>

<para>
How does this work? Well <command>configure</command> is a script that

<itemizedlist>
  <listitem><para>
  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
  </para></listitem>
  <listitem><para>
  creates recursive <filename>Makefile</filename> files by filling in the substitutions in the corresponding <filename>Makefile.in</filename> files.
  </para></listitem>
</itemizedlist>
</para>
<para>
The <filename>Makefile.in</filename> are <quote>input</quote> files&mdash;templates which provide basic information for the <filename>Makefile</filename>s to be produced from them by filling in some system dependent information. They are generated by the <command>Automake</command> utility from the <filename>Makefile.am</filename> files.
</para>
<para>
The process of going from <filename>Makefile.am</filename> (<filename>.am</filename> denotes <quote>Automake</quote> template files) to <filename>Makefile</filename> files is handled automatically by the &kdevelop; &promanag;, using the <command>Autoconf</command> utility, <command>M4</command> macros and other arcana we need not go into here.
</para>
<para>
So when <command>make</command> runs, it automatically picks up the correct pieces from the current environment, such as compilers and libraries. Similarly, <command>make install</command> puts your application components, such as executables, documentation and data files in the correct places for that environment.
</para>

<para>
If you distribute your application as a <quote>tarball</quote> (a single compressed file that &kdevelop; can create for you), it will include the <filename>Makefile.in</filename> files and the <filename>configure</filename> script file, so the recipient can compile, build and install your application without having <command>Automake</command>, <command>Autoconf</command> or &kdevelop; on their machine. The <filename>Makefile.am</filename> files are also included, just in case the receiver needs to do any source-code modifications.
</para>
<note><para>
The rules are rather different if you distribute via a web-based source-code repository such as &kde; &cvs;.
</para></note>

</sect2> <!--  automake-manager-basics -->

<sect2 id="automake-manager-basics-summary">
<title>Summary of What Automake Manager Does</title>

<itemizedlist>
  <listitem><para>
  Generates <filename>Makefile.am</filename> files in subdirectories it knows as <quote>subprojects</quote>.
  </para></listitem>
  <listitem><para>
  Updates <filename>Makefile.am</filename> files as the project structure changes.
  </para></listitem>
  <listitem><para>
  Updates <filename>Makefile.am</filename> files as files are added to or removed from the project.
  </para></listitem>
  <listitem><para>
  Accepts definitions of how the various files are to be built or installed and modifies the <filename>Makefile.am</filename> accordingly.
  </para></listitem>
  <listitem><para>
  Accepts parameters used in building or installing (&eg; library names) and ensures that they are used in the required compilation and build steps.
  </para></listitem>
</itemizedlist>

</sect2> <!--  automake-manager-basics-summary -->

<sect2 id="automake-file-contents">
<title>Contents of Automake Files</title>

<para>
A <filename>Makefile.am</filename> file has lines containing variable-names followed by an equals sign and a list of files or parameter values. The <quote>variables</quote> have two-part names, such as <varname>bin_PROGRAMS</varname>, <varname>myapp_SOURCES</varname> or <varname>kdelnk_DATA</varname>. The second part is called the <emphasis>primary</emphasis> and represents something from which to build or install. The first part is called the <emphasis>prefix</emphasis> and represents:
</para>
<itemizedlist>
  <listitem><para>
  A <emphasis>directory</emphasis> in which to do installation (&eg; <filename>bin</filename>),
  </para></listitem>
  <listitem><para>
  A <emphasis>qualifier</emphasis> for the primary (&eg; <varname>myapp</varname> for <varname>SOURCES</varname>, indicating that the source files listed after <varname>myapp_SOURCES</varname> go into building <filename>myapp</filename>),
  </para></listitem>
  <listitem><para>
  A special <emphasis>prefix</emphasis> <varname>noinst</varname> (short for <quote>no installation</quote>), usually used to list program header files (<filename>.h</filename>),
  </para></listitem>
  <listitem><para>
  Or the special prefix <varname>EXTRA</varname>, for <emphasis>configuration-dependent</emphasis> stuff.
  </para></listitem>
</itemizedlist>

<para>
For more information on <command>Automake</command> and <filename>Makefile.am</filename> files, look up <userinput>info Automake</userinput>.
</para>
<para>
Basically, &automanag; creates and updates the variable-names and lists of files or parameters. See the following example of a <filename>Makefile.am</filename> for a typical application, called <filename>myapp</filename>.
</para>

<screen>
## 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_TDEPRINT)

# 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
</screen>

<para>
As you can see, many of the items on the right hand side are symbols of the form <varname>$(xxx)</varname>. These are <emphasis>environment variables</emphasis> which are defined in the actual &kde; environment and are substituted with real values when <command>./configure</command> generates the final <filename>Makefile</filename> files in the receiving machine.
</para>

<para>
Also, sometime after you have started with &kdevelop;, it is a good idea to run the command <command>./configure --help</command>, 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:

<screen>
./configure --prefix=/where/you/wish
</screen>
will re-direct the entire installation to a directory structure of your choice, by changing the internal variable <varname>$(prefix)</varname> to value <filename class="directory">/where/you/wish</filename>.
</para>

</sect2> <!-- automake-file-contents -->

</sect1> <!--  automake-manager-summary -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="automake-manager-operation">
<title>Automake Manager Operation</title>

<para>
In this chapter you will find a basic description of the &automanag; elements and how to use them. This covers:
<itemizedlist>
  <listitem><para>
  <link linkend="automake-manager-operation-window">The &automanag; Window</link> describes the basic structure of the &automanag; main window.
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation-survey-window">The Overall View Window</link> describes the elements of the upper subwindow.
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation-detail-window">The Detail View Window</link> describes the elements of the lower subwindow.
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation-navigate">Navigating in the &automanag;</link> lists some basic operations you can perform in the &automanag;.
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation-popups">Popup Menus in the &automanag;</link> describes the windows which will pop up when you select an action in the &automanag;.
  </para></listitem>
</itemizedlist>
</para>

<sect2 id="automake-manager-operation-window">
<title>The &automanag; Window</title>

<informaltable frame="none">
<tgroup cols="2"><tbody><row>
  <entry><inlinemediaobject>
    <imageobject>
      <imagedata fileref="automakemanager.png" format="PNG"/>
    </imageobject>
  </inlinemediaobject></entry>
  <entry valign="top"><itemizedlist>
    <listitem><para>
    &automanag; runs in a split window. The top part is called the <emphasis>Overall View</emphasis> and the bottom part is called the <emphasis>Detail View</emphasis>. 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.
    </para></listitem>
    <listitem><para>
    On top of each view there is a <emphasis>toolbar</emphasis>, 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.
    </para></listitem>
    <listitem><para>
    In IDEAl mode there are two additional small buttons in the &automanag; window titlebar left hand side &ndash; a triangular shaped right arrow, and a dot button. The arrow button is used to <emphasis>close the window</emphasis>. The dot button on the other hand will <emphasis>keep the window open</emphasis> even if another &kdevelop; window has been selected. (Otherwise the &automanag; window will automatically close whenever another window gets the input focus.)
    </para></listitem>
  </itemizedlist></entry>
</row></tbody></tgroup>
</informaltable>

</sect2> <!-- automake-manager-operation-window -->

<sect2 id="automake-manager-operation-survey-window">
<title>The Overall View Window</title>

<para>
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 <filename>Makefile.am</filename> file and is known in &automanag; as a <emphasis>subproject</emphasis>. There are three typical subprojects in a &kde;-based project as shown in the above illustration:
</para>

<itemizedlist>
  <listitem><para>
  <filename>src</filename> &ndash; source-code files for your application,
  </para></listitem>
  <listitem><para>
  <filename>doc</filename> &ndash; your user manual or Handbook,
  </para></listitem>
  <listitem><para>
  <filename>po</filename> &ndash; extracts of strings in your source-code files that require translation into other human languages (&eg; window titles, menu names, button labels, dialog box text and messages of various kinds).
  </para></listitem>
</itemizedlist>

<para>
Note that the <filename>doc</filename> subproject always has an <filename>en</filename> subproject, which you can see if you click on the <symbol>+</symbol> symbol next to the word <filename>doc</filename>. 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 <filename>de</filename> (German) or <filename>fr</filename> (French). The strings in the <filename>po</filename> subproject may also be translated and stored in other files in <filename>po</filename>, thus allowing your application to be operated by people who do not know English.
</para>

<note><para>
The <filename>doc</filename> and <filename>po</filename> subprojects serve different purposes. <filename>doc</filename> contains <emphasis>documentation</emphasis> like a user manual, <filename>po</filename> contains translatable text strings of the <emphasis>user interface</emphasis> which is integrated in the source code of this application.
</para></note>

<para>
The overall view window serves&mdash;amongst other things&mdash;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.
</para>

</sect2> <!-- automake-manager-operation-survey-window -->

<sect2 id="automake-manager-operation-detail-window">
<title>The Detail View Window</title>

<para>
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.
</para>

<sect3>
<title>Targets</title>

<para>The tree-list in the detail view has two levels. The top level consists of so-called &automanag; <emphasis>targets</emphasis> and the next level contains lists of files that go to make up each target.
</para>

<para>
This concept of an &automanag; target differs somewhat from what a <filename>Makefile</filename> target usually is. In short:</para>
<itemizedlist>
  <listitem><para>
  The definition of how a set of files is to be compiled, built or installed is known as a <emphasis>target</emphasis> in &automanag;, but as a <emphasis>variable</emphasis> in <command>Automake</command> itself.
  </para></listitem>
  <listitem><para>
  A <emphasis>target</emphasis> in <command>make</command> is often something quite different, being the parameter of a <command>make</command> command (&eg; <userinput>make install</userinput>, <userinput>make clean</userinput>).
  </para>
  <para>
  However some <filename>Makefile.am</filename> variables do represent an underlying <emphasis>sub-target</emphasis> in <command>make</command>.
  </para></listitem>
</itemizedlist>

</sect3>
</sect2> <!-- automake-manager-operation-detail-window -->

<sect2 id="automake-manager-operation-navigate">
<title>Navigating in the &automanag;</title>

<para>
In both the overall and the detail view you can left-click on the <symbol>+</symbol> or <symbol>-</symbol> next to a subproject or target name to expand or contract the tree view. If you do that with a <emphasis>subproject</emphasis> in the overall view, it shows or hides the subprojects at the next level down (if any). If you do it with a <emphasis>target</emphasis> in the detail view, it shows or hides the list of files that go into that target.
</para>

<variablelist>
<varlistentry>
<term>Opening a file for Edit</term>
<listitem>
<para>If you <emphasis>&LMB; click</emphasis> on a file name in the detail
view, the corresponding file opens up in &kdevelop;'s editing window.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Activating the &automanag; Toolbar Buttons</term>
<listitem>
<para>
If you <emphasis>&LMB; click</emphasis> 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.</para>

<note>
  <para>
  It is recommended that you use the <emphasis>right mouse-button and popup menus</emphasis>, rather than the toolbar buttons, because it is then much easier to see and understand what you are doing.
  </para>
  <para>
  Operations on subprojects and targets have far-reaching effects on the structure, compilation, building and installation of your application.
  </para>
</note>
</listitem>
</varlistentry>

<varlistentry>
<term>Selecting Actions/Popup Menus</term>
<listitem>
<para>
If you <emphasis>&RMB; click</emphasis> 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.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2> <!-- automake-manager-operation-navigate -->

<sect2 id="automake-manager-operation-popups">
<title>Popup Menus in the &automanag;</title>

<para>
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.
</para>
<!-- ### add a link to this chapter when ready -->

<sect3 id="automake-manager-operation-popups-file">
<title>The Popup Menu for a File</title>

<para>
When you &RMB; click on a <emphasis>file name</emphasis> 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 <filename>hi-16app-myapp.png</filename> icon file was selected from the <guilabel>Icon data in myapp</guilabel> target of the <guilabel>myapp/src</guilabel> subproject.
</para>

<informaltable frame="none">
<tgroup cols="2"><tbody><row>
  <entry><inlinemediaobject>
    <imageobject>
      <imagedata fileref="automake-file-popup.png" format="PNG"/>
    </imageobject>
  </inlinemediaobject></entry>
  <entry valign="bottom"><itemizedlist>
    <listitem><para>
    The main popup-menu item for a file is to <guimenuitem>Remove</guimenuitem> the file from its target (&ie; it will no longer be used to compile, build or install that target).
    </para></listitem>
    <listitem><para>
    The <guimenuitem>CVS</guimenuitem> item offers a variety of CVS operations on the file.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Open With</guimenuitem> item allows you to open the file with a variety of editors or with any application at all (&eg; you can open the icon file in our example with <application>KIcon</application>).
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Perforce</guimenuitem> item is used for similar operations as in CVS using the commercial <quote><application>Perforce</application></quote> version control system.
    </para></listitem>
  </itemizedlist></entry>
</row></tbody></tgroup>
</informaltable>

</sect3> <!-- automake-manager-operation-popups-file -->

<sect3 id="automake-manager-operation-popups-target">
<title>The Popup Menu for a Target</title>

<para>
When you right-click on a <emphasis>target</emphasis> 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 <guilabel>myapp (Program in bin)</guilabel> target of the <guilabel>myapp/src</guilabel> subproject was selected.
</para>

<informaltable frame="none">
<tgroup cols="2"><tbody><row>
  <entry><inlinemediaobject>
    <imageobject>
      <imagedata fileref="automake-target-popup.png" format="PNG"/>
    </imageobject>
  </inlinemediaobject></entry>
  <entry valign="bottom"><itemizedlist>
    <listitem><para>
    The <guimenuitem>Options</guimenuitem> 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.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Create New File</guimenuitem> 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).
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Add Existing Files</guimenuitem> item brings up a dialog box in which you can add an already existing file to this target.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Remove</guimenuitem> item for a target allows you to logically remove the target and all its files from the project structure.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Make Target Active</guimenuitem> item only applies to targets containing source code files. New files will always be added to such an active target.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Build Target</guimenuitem> item calls all necessary compile and make operations to build the code for this target only.
    </para></listitem>
  </itemizedlist></entry>
</row></tbody></tgroup>
</informaltable>

</sect3> <!-- automake-manager-operation-popups-target -->

<sect3 id="automake-manager-operation-popups-subproject">
<title>The Popup Menu for a Subproject</title>

<para>
When you &RMB; click on a <emphasis>subproject</emphasis> 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.
</para>


<informaltable frame="none">
<tgroup cols="2"><tbody><row>
  <entry><inlinemediaobject>
    <imageobject>
      <imagedata fileref="automake-subproject-popup.png" format="PNG"/>
    </imageobject>
  </inlinemediaobject></entry>
  <entry valign="bottom"><itemizedlist>
    <listitem><para>
    The <guimenuitem>Options</guimenuitem> 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.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Add Subproject</guimenuitem> item creates a new directory and skeleton Makefile.am file.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Add Target</guimenuitem> item pops up a dialog in which you can set the rules for compiling, building or installing a group of files within your subproject.
    </para></listitem>
    <listitem><para>
    <guimenuitem>Add Service</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Add Application</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Add Existing Subprojects</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Remove Subproject</guimenuitem> item in the popup menu for a subproject is the proper way to remove a subproject. It will adjust the <filename>Makefile.am</filename> 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.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Build</guimenuitem> item calls all necessary compile and make operations to build the code for this subproject only.
    </para></listitem>
    <listitem><para>
    <guimenuitem>Force Reedit</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Clean</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Install</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Install (as root user)</guimenuitem> (... to be written ...)
    </para></listitem>
  </itemizedlist></entry>
</row></tbody></tgroup>
</informaltable>

</sect3> <!-- automake-manager-operation-popups-subproject -->

</sect2> <!-- automake-manager-operation-popups -->

</sect1> <!-- automake-manager-operation -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="autoproject">
<title>Automake Projects</title>
<indexterm zone="autoproject"><primary><command>autoproject</command></primary></indexterm>
<indexterm zone="autoproject"><primary>&automake;</primary></indexterm>
<indexterm zone="autoproject"><primary>&autoconf;</primary></indexterm>
<indexterm zone="autoproject"><primary>&libtool;</primary></indexterm>

<para>
(... to be written ...)
</para>


<sect2 id="autoconf">
<title>Autoconf</title>
<indexterm zone="autoconf"><primary><filename>configure</filename> script</primary></indexterm>
<indexterm zone="autoconf"><primary><filename>config.status</filename> script</primary></indexterm>
<indexterm zone="autoconf"><primary><filename>Makefile.in</filename></primary></indexterm>
<indexterm zone="autoconf"><primary><filename>config.h.in</filename></primary></indexterm>

<para>
<filename>Makefile.in</filename> into <filename>Makefile</filename>
</para>

<programlisting>
prefix = @prefix@
INSTALL = @INSTALL@
build_triplet = @build@
CXX = @CXX@
</programlisting>

<programlisting>
prefix = /home/bernd/trinity
INSTALL = /usr/bin/ginstall -c -p
build_triplet = i686-pc-linux-gnu
CXX = g++
</programlisting>

<para>
<filename>config.h.in</filename> into <filename>config.h</filename>
</para>

<programlisting>
/* Define if you have libz */
#undef HAVE_LIBZ
/* The size of a `int', as computed by sizeof. */
#undef SIZEOF_INT
</programlisting>

<programlisting>
/* Define if you have libz */
#define HAVE_LIBZ 1
/* The size of a `int', as computed by sizeof. */
#define SIZEOF_INT 4
</programlisting>

</sect2> <!-- autoconf -->


<sect2 id="automake">
<title>Automake</title>

<para>
(... to be written ...)
</para>

</sect2> <!--automake  -->


<sect2 id="automake-manager">
<title>&kdevelop;'s &automanag;</title>

<figure id="screenshot-automake-manager" float="1">
<title>A screenshot of the automake manager</title>
<mediaobject>
<imageobject><imagedata fileref="automake-manager.png"/></imageobject>
</mediaobject>
</figure>

</sect2> <!-- automake-manager -->


<sect2 id="automakelibrary">
<title>Building and Installing Libraries</title>

<para>
<itemizedlist>
<listitem><para>
  -rpath
</para></listitem>
<listitem><para>
  PIC
</para></listitem>
<listitem><para>
  static
</para></listitem>
<listitem><para>
  plugins: no-undefined
</para></listitem>
</itemizedlist>
</para>

</sect2> <!-- automakelibrary -->

</sect1> <!-- autoproject -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="customproject">
<title>Custom Makefiles and Build Scripts</title>
<indexterm zone="customproject"><primary><filename>Makefile</filename></primary></indexterm>
<indexterm zone="customproject"><primary><filename>build.xml</filename></primary></indexterm>

<para>
(... to be written ...)
</para>

</sect1> <!-- customproject -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="compileroptions">
<title>Compiler Options</title>

<para>
(... to be written ...)
</para>

</sect1> <!-- compileroptions -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="makeoptions">
<title>Make Options</title>

<para>
(... to be written ...)
</para>

</sect1> <!-- makeoptions -->

</chapter> <!-- project-management -->