<!-- ============= Build ====================== -->
 <chapter id="building">
  <title>Building</title>
  <para>
   Anjuta handles <application>autotools</application> projects. It is able to cope with other kinds of
   projects, such as projects using a user-written Makefile, but the current build
   interface is targeted at autotools projects. Some knowledge of them is
   useful to better understand the way a project is built.
  </para>
  <para>
   An autotools project is built in three steps:
  </para>
  <para>
     <orderedlist>
      <listitem><para>Generate</para></listitem>
      <listitem><para>Configure</para></listitem>
      <listitem><para>Build</para></listitem>
     </orderedlist>
  </para>
  <para>
   <emphasis>Build</emphasis> is the main step in which all target files are
   generated from the source files. It can be divided into
   two subphases: <emphasis>Compile</emphasis> and <emphasis>Link</emphasis>.
   In the <emphasis>Compile</emphasis> phase each object file is generated from 
   its corresponding source file. For instance, a source file <filename>hello.c</filename>
   will generate <filename>hello.o</filename> after compilation. Usually you do not need 
   to worry about these object files &mdash; just think of them as intermediate files. 
   In the <emphasis>Link</emphasis> phase, all object files and libraries
   are linked together to create the final executable.
   Some programming languages do not need a <emphasis>Compile</emphasis>
   and a <emphasis>Link</emphasis> phase. Moreover the <emphasis>Build</emphasis> step
   may be used to generate other files, like documentation which doesn't need such phases.
  </para>
  <para>
   <emphasis>Configure</emphasis> is the step in which the source tree is adjusted
   to your system. <application>autotools</application> projects can be built on a wide range of systems using
   different compilers and having different library functions. This step runs a
   script named <filename>configure</filename> that will check for various characteristics
   of your system
   and create some of the files required to perform a build (such as 
   <filename>Makefile</filename> and <filename>config.h</filename>).
   This step is used to select build options, too; for
   instance, a build option may disable optimization to make debugging easier or disable some
   experimental part of a program.
  </para>
  <para>
   <emphasis>Generate</emphasis> is the step in which the <filename>configure</filename>
   script and other related files are created. The <filename>configure</filename>
   script used above needs to run on
   various systems and checks a lot of things. It would be quite difficult to write it
   by hand. Moreover <application>autotools</application> enforces some project organization rules
   such as the presence of some mandatory files: <filename>NEWS</filename> and <filename>COPYING</filename>, for example.
   It includes several tools
   to create necessary files from simpler files written by the developer
   such as <filename>configure.in</filename> (or <filename>configure.ac</filename>) and
   <filename>Makefile.am</filename>. All these tools are commonly run
   from a script named <filename>autogen.sh</filename> in the project directory. This step is useful only
   for a developer (someone modifying the source files), as the
   <filename>configure</filename> script depends only on the source files, and is distributed within the
   project package.
   Note that the makefiles created by <application>configure</application> include some rules
   to automatically regenerate the project when needed, so it often not needed to
   rerun it directly.
 </para>
 <para>
  Read the info pages of <ulink type="info" url="info:automake"><application>automake</application></ulink> 
  and <ulink type="info" url="info:autoconf"><application>autoconf</application></ulink> for more 
  details on how these tools work.
 </para>


 <!-- Build: Generate and Configure -->

 <sect1 id="build-configure">
  <title>Generate and Configure</title>
  <sect2 id="configure">
   <title>Configure a project</title>
   <para>
    You need to run this step before being able to build your project. This is
    usually run only once at the beginning of the first build process &mdash;
    for example, just after you have extracted a source tarball of a
    project distribution. After that, configuration is automatically handled by the 
    subsequent build processes.
    If you have used the <emphasis>Application Wizard</emphasis> 
    to create the application, then you will not need to run this 
    separately: the wizard will run it as a part of the project generation process.
   </para>
   <para>
    There is no requirement to run this only once. It can be 
    run at any time, usually when the configuration options need to be changed. One thing to 
    note is that if the <filename>config.h</filename> file in the top level directory is 
    changed, running <filename>configure</filename> again will not overwrite it.
   </para>
   <para>
    Both generate and configure steps are launched with a single menu item:
    <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Configure Project&hellip;</guimenuitem></menuchoice>.
    This menu item brings a dialog where you can choose:
    <itemizedlist>
     <listitem><para>Whether you want to run the generate step or not</para>
      <para>
       The generate step needs to be run once at the beginning of the project; then it is automatically
       handled by the build process. You can force it to run by checking the checkbox
       <interface>Regenerate project</interface>; you might do this if you encounter
       difficulties while building a project (e.g. if you receive build errors
       after you've modified lots of build files).
      </para>
     </listitem>
     <listitem><para>The configuration name</para>
      <para>
       This name is used to refer to each configuration. Some configurations (Default,
       Debug, Optimized) are already defined by default. One configuration includes
       a build directory and some configuration options.
      </para>
     </listitem>
     <listitem><para>The build directory</para>
      <para>
       This is the build directory name. In the Default configuration, it is the same
       directory as the source directory but autotools supports building in a
       different directory.
      </para> 
      <note><para>
       Each configuration must have a different build directory and if one configuration
       uses the source directory, you cannot have other configurations at the same time.
       You need to run <menuchoice><guisubmenu>Build</guisubmenu>
       <guimenuitem>Remove Configuration</guimenuitem></menuchoice> on the configuration
       using the source directory before adding a new configuration.
      </para></note>
     </listitem>
     <listitem><para>Configure options</para>
      <para>
       These options are passed to the <filename>configure</filename> script. Some are standard, such as --prefix and CFLAGS; others depend on the project. You can get a list of allowed configuration options by
       running the <filename>configure</filename> script with the <option>--help</option> argument.
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </sect2>
  <sect2 id="select-configure">
   <title>Select a configuration</title>
   <para>
    If you have created different configurations, you can select which one is active by
    selecting it in <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Select Configuration</guimenuitem></menuchoice>.
   </para>
  </sect2>
  <sect2 id="clean-configure">
   <title>Clean a configuration</title>
   <para>
    To clean the project and leave it in a state that requires rerunning the
    configure step, choose <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Remove Configuration</guimenuitem></menuchoice>.
    It run <command>make distclean</command> and deletes more files than <guimenuitem>Clean Project</guimenuitem>.
    In other words, it leaves the project
    as though it has just been extracted from a distribution tarball. Note
    that it does not remove the configuration directory itself; you can
    do that yourself if you like.
   </para>
  </sect2>
 </sect1>


 <!-- Build: Compile and Build -->

 <sect1 id="build-compile-and-build">
  <title>Compile and Build</title>
  <sect2 id="build-compile">
   <title>Compiling a file</title>
   <para>
    In a project, individual source files can be compiled separately into objects 
    (<filename>*.o</filename> files). Although you do not have to worry about these object 
    files, sometimes it is handy to compile a file first (for example, to make sure there are 
    no syntax errors). Building a whole project can take a lot of time, especially in the case of 
    larger and more complex applications. Therefore, you will probably go through a series of 
    edit-compile iterations while developing a project.
   </para>
   <para>
    To compile a file, choose the menu item <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Compile</guimenuitem></menuchoice> or  press <keycap>F11</keycap>.
    This will compile the active file.
   </para>
  </sect2>

  <sect2 id="build-build">
   <title>Building an executable</title>
   <para>
    <application>Anjuta</application> has no separate link command, simply because 
    it is not necessary. The build process will compile all source files and link them together 
    along with the necessary libraries. The build command will not recompile those files which are 
    already up-to-date (this is called the <emphasis>dependency check</emphasis>). 
    If you have already compiled all files individually, then the only thing the build 
    step performs is the link. If you have already built the project and no dependent file has been 
    modified, even the link stage will be skipped.
   </para>
   <para>
    So how exactly does the dependency check influence project development? 
    If you have modified a file, then all of the source files that depend on the modified 
    file are recompiled. All files (not just the object files and executable) in the 
    project are checked for these dependencies during the build process. If it is found that 
    a particular file is dependent on some other file which has been modified, then that file 
    will be regenerated.
   </para>
   <para>
    Can you imagine how your life (as a programmer) would be if the dependency check were not there? If you 
    cannot answer just yet, then you will find out when you start developing big projects!
   </para>
   <para>
    <menuchoice><guisubmenu>Build</guisubmenu><guimenuitem>Build</guimenuitem></menuchoice> 
    will build all files in the directory of the currently active file. 
   </para>
   <para>
    <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Build Project</guimenuitem></menuchoice> will build 
    the whole project &mdash; all subdirectories are built recursively.
   </para>
  </sect2>
 </sect1>


 <!-- Build: Other operations -->

 <sect1 id="build-other">
  <title>Other operations</title>
  <sect2 id="build-dist">
   <title>Creating a distribution package</title>
   <para>
    To build a tarball distribution of the project choose <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Build Tarball</guimenuitem></menuchoice>. This will create a 
    tarball (<filename>*.tar.gz</filename>) and put it in the top-level project directory. 
    Copy the file to a safe place for distribution.
   </para>
  </sect2>
  <sect2 id="build-install">
   <title>Installing a project</title>
   <para>
    Choosing the menu item <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Install</guimenuitem></menuchoice> will install the generated 
    application on your system. 
   </para>
   <note>
    <title>System-wide installation</title>
    <para>
     You must be logged in as root to perform a system-wide install. Also note that for a GNOME 
     application to use the pixmaps in the project, it must be installed as a system-wide 
     application. Otherwise, when the application is executed in your project, there will be 
     lots of &quot;pixmap not found&quot; errors. You can configure Anjuta to use <command>sudo</command>
     or <command>su</command> before installing the project in the build preferences.
    </para>
   </note>
  </sect2>
  <sect2 id="build-clean">
   <title>Cleaning</title>
   <para>
    This deletes all of the files generated by the build process, including
    all object files (<filename>*.o</filename> files) and the executable(s).
    It can be applied on one directory or the whole project.
   </para>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Clean Project</guimenuitem></menuchoice> to clean all project
    files.
   </para>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Build</guisubmenu>
    <guimenuitem>Clean</guimenuitem></menuchoice> to clean only the directory
    of the current active file.
   </para>
  </sect2>

 </sect1>

</chapter>
