anjuta r4174 - in trunk: . manuals/anjuta-manual manuals/anjuta-manual/C
- From: sgranjoux svn gnome org
- To: svn-commits-list gnome org
- Subject: anjuta r4174 - in trunk: . manuals/anjuta-manual manuals/anjuta-manual/C
- Date: Fri, 22 Aug 2008 16:00:07 +0000 (UTC)
Author: sgranjoux
Date: Fri Aug 22 16:00:07 2008
New Revision: 4174
URL: http://svn.gnome.org/viewvc/anjuta?rev=4174&view=rev
Log:
* manuals/anjuta-manual/C/projects.xml,
manuals/anjuta-manual/C/anjuta-manual.xml,
(added) manuals/anjuta-manual/C/build.xml,
manuals/anjuta-manual/Makefile.am:
Update build documentation
Added:
trunk/manuals/anjuta-manual/C/build.xml
Modified:
trunk/ChangeLog
trunk/manuals/anjuta-manual/C/anjuta-manual.xml
trunk/manuals/anjuta-manual/C/projects.xml
trunk/manuals/anjuta-manual/Makefile.am
Modified: trunk/manuals/anjuta-manual/C/anjuta-manual.xml
==============================================================================
--- trunk/manuals/anjuta-manual/C/anjuta-manual.xml (original)
+++ trunk/manuals/anjuta-manual/C/anjuta-manual.xml Fri Aug 22 16:00:07 2008
@@ -7,6 +7,7 @@
<!ENTITY interface SYSTEM "interface.xml">
<!ENTITY fileoperations SYSTEM "fileoperations.xml">
<!ENTITY projects SYSTEM "projects.xml">
+ <!ENTITY build SYSTEM "build.xml">
<!ENTITY debugger SYSTEM "debugger.xml">
<!ENTITY preferences SYSTEM "preferences.xml">
<!ENTITY tools SYSTEM "tools.xml">
@@ -96,6 +97,8 @@
&fileoperations;
<!-- Project Management -->
&projects;
+ <!-- Build -->
+ &build;
<!-- Debugging -->
&debugger;
<!-- Preferences -->
Added: trunk/manuals/anjuta-manual/C/build.xml
==============================================================================
--- (empty file)
+++ trunk/manuals/anjuta-manual/C/build.xml Fri Aug 22 16:00:07 2008
@@ -0,0 +1,274 @@
+<!-- ============= Build ====================== -->
+ <chapter id="building">
+ <title>Building</title>
+ <para>
+ Anjuta handles autotools projects. It is able to cope with other kinds of
+ project like 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 in
+ two sub phases: <emphasis>Compile</emphasis> and <emphasis>Link</emphasis>.
+ In <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 — just think of them as intermediate files.
+ In <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
+ is used to generate other files, like documentation which don't need such phases.
+ </para>
+ <para>
+ <emphasis>Configure</emphasis> is the step in which the sources tree is adjusted
+ to your system. autotools 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, 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 lots of things. It is quite difficult to write it
+ by hand. Moreover the autotools stuff enforces some rules to organize a
+ project like some mandatory files: <filename>NEWS</filename> or <filename>COPYING</filename>.
+ It includes several tools
+ to check and create all necessary files from simpler files written by the developper
+ like <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 sources files, it is distributed within the
+ project package.
+ Note that, the makefiles created by configure included 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 —
+ 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…</guimenuitem></menuchoice>.
+ This menu item brings a dialog where you can choose:
+ <itemizedlist>
+ <listitem><para>If you want to run the generate step or not</para>
+ <para>
+ It needs to be run once at the beginning of the project then it is automatically
+ handled by the build process. You can force to run it by checking the check box
+ <interface>Regenerate project</interface> in cases you encounter some
+ difficulties while building the projects (such as lots of errors reported
+ due to mis-synchronization after modifying 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 than the source directory but autotools support to build 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 like prefix, CFLAGS,
+ … some depends on the project. You can get a list of allowed configuration option by
+ running the <filename>configure</filename> script with --help argument.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2 id="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="configure">
+ <title>Clean a configuration</title>
+ <para>
+ To clean the project and leave it in a state that requires to rerun the
+ configure step, you have to choose <menuchoice><guisubmenu>Build</guisubmenu>
+ <guimenuitem>Remove Configuration</guimenuitem></menuchoice>.
+ It run "make distclean" 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 but you can
+ do it.
+ </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, the 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-edit-compile-.... loops 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 the source files and link them together
+ along with the libraries. The build command will note recompile those files which are
+ already up-to-date (this is called the <emphasis>dependency check</emphasis>).
+ If you have already compiled all of the 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 the 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 only 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 re-generated.
+ </para>
+ <para>
+ Since you have now got a rough understanding of the value of the dependency check, can
+ you imagine how your life (as a programmer) would be if it had not been there? If you
+ cannot answer just yet, then will find out when you start developing big projects!
+ </para>
+ <para>
+ <menuchoice><guisubmenu>Build</guisubmenu><guimenuitem>Build</guimenuitem></menuchoice>
+ will build all of the 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 — all of the 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 the 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 "pixmap not found" 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 the 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>
Modified: trunk/manuals/anjuta-manual/C/projects.xml
==============================================================================
--- trunk/manuals/anjuta-manual/C/projects.xml (original)
+++ trunk/manuals/anjuta-manual/C/projects.xml Fri Aug 22 16:00:07 2008
@@ -757,224 +757,4 @@
</sect2>
</sect1>
- <sect1 id="project-build">
- <title>Compiling and Building</title>
- <sect2 id="project-basics">
- <title>Overview</title>
- <para>
- An executable for a project is generated in two steps:
- </para>
- <para>
- <orderedlist>
- <listitem><para>Compiling</para></listitem>
- <listitem><para>Linking</para></listitem>
- </orderedlist>
- </para>
- <para>
- These steps are collectively known as <emphasis>Building</emphasis>. Some other
- steps may also be involved in the build process, but for the sake of
- simplicity, we will only look at these two steps.
- </para>
- <para>
- <emphasis>Compiling</emphasis> is the step in which object files are generated from
- their corresponding source files. 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 — just think of them as intermediate files
- involved in creating the final executable.
- </para>
- <para>
- Once the object files (<filename>*.o</filename> files) are ready, they are all linked
- together (along with any libraries) to generate the final executable. This step is
- called <emphasis>Linking</emphasis>.
- </para>
- </sect2>
- <sect2 id="compiling-project">
- <title>Compiling the source</title>
- <para>
- In a project, the 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-edit-compile-.... loops while a developing the 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="building-exec">
- <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 the source files and link them together
- along with the libraries. The build command will note recompile those files which are
- already up-to-date (this is called the <emphasis>dependency check</emphasis>).
- If you have already compiled all of the 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 the 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 only 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 re-generated.
- </para>
- <para>
- Since you have now got a rough understanding of the value of the dependency check, can
- you imagine how your life (as a programmer) would be if it had not been there? If you
- cannot answer just yet, then will find out when you start developing big projects!
- </para>
- <para>
- <menuchoice><guisubmenu>Build</guisubmenu><guimenuitem>Build</guimenuitem></menuchoice>
- will build all of the files in the <filename class="directory">src</filename> (source)
- directory, and generate the executable. <menuchoice><guisubmenu>Build</guisubmenu>
- <guimenuitem>Build Project</guimenuitem></menuchoice> will build
- the whole project — all of the subdirectories (including
- <filename class="directory">src</filename>), are built recursively.
- </para>
- </sect2>
- <sect2 id="build-dist">
- <title>Creating a distribution package</title>
- <para>
- To build the 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>Install</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 "pixmap not found" 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="configure">
- <title>Configure</title>
- <para>
- To run the <filename>configure</filename> script found in the top level project directory,
- choose the menu item <menuchoice><guisubmenu>Build</guisubmenu>
- <guimenuitem>Run Configure…</guimenuitem></menuchoice>. The script will determine the system
- configuration and create some of the files required to perform a build (such as
- <filename>Makefile</filename> and <filename>config.h</filename>). This is necessary because
- the application may depend on specific configuration of some of these options.
- </para>
- <important>
- <title>When to run configure</title>
- <para>
- Until you run <filename>configure</filename>, you cannot start building the
- project.
- </para>
- </important>
- <para>
- The <filename>configure</filename> script is (usually) run only once at the beginning of
- the first build process — 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 <filename>configure</filename>
- separately: the wizard will run it as a part of the project generation process.
- </para>
- <para>
- You can also supply additional options to the configuration script. After choosing the
- <guimenuitem>Run Configure…</guimenuitem> menu item, a dialog will appear to prompt for additional
- options.
- </para>
- <figure>
- <title>Configure options dialog</title>
- <screenshot>
- <screeninfo>Configure options dialog</screeninfo>
- <graphic fileref="figures/configure_dlg.png" format="PNG" srccredit="jhs"></graphic>
- </screenshot>
- </figure>
- <para>
- Enter any options (or leave it blank to accept the defaults) and click
- <guibutton>OK</guibutton>. To find out the options available to the
- <filename>configure</filename> script, enter <userinput>--help</userinput>
- in the option entry box and click <guibutton>OK</guibutton>. The options will be displayed
- in the <interface>Message window</interface>.
- </para>
- <para>
- There is no requirement to run <filename>configure</filename> 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>
- </sect2>
- <sect2 id="auto-generation">
- <title>Auto generate</title>
- <para>
- Auto generation consists of two steps: running <application>automake</application> and
- then running <application>autoconf</application>. If an executable
- <filename>autogen.sh</filename> script is found in the top level project
- directory, this file will be executed instead of the two steps.
- Like <emphasis>configuration</emphasis>, auto generation is automatically handled
- by the build process. It can also be run in cases where it is difficult to configure
- the project (such as lots of errors reported due to mis-synchronization after modifying
- lots of build files).
- </para>
- <note>
- <title>When to run autogen.sh</title>
- <para>
- Unlike configuration, auto generation does not need to be run even
- once — in fact, it does not need to be run at all! The option is available because it
- can be handy in some circumstances.
- </para>
- </note>
- <para>
- Choose the menu item <menuchoice><guisubmenu>Build</guisubmenu>
- <guimenuitem>Run Autogenerate…</guimenuitem></menuchoice> to auto generate the project.
- </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>
- </sect2>
- <sect2 id="build-clean">
- <title>Clean</title>
- <para>
- This option cleans the project and leaves it in a state that requires
- <guimenuitem>Build Project</guimenuitem> to be performed. It deletes all of the
- files generated by the build process, including all object files
- (<filename>*.o</filename> files) and the executable(s) in the
- <filename class="directory">src</filename> directory (and other directories).
- </para>
- <para>
- Choose the menu item <menuchoice><guisubmenu>Build</guisubmenu>
- <guimenuitem>Clean</guimenuitem></menuchoice> to clean the project.
- </para>
- </sect2>
- <sect2 id="build-cleanall">
- <title>Clean Project</title>
- <para>
- There is not a great deal to say about <guimenuitem>Clean Project</guimenuitem> (which might
- also be called <emphasis>Clean distribution</emphasis>, or <emphasis>clean dist</emphasis>
- for short). It cleans the project and leaves it in a state that requires
- <guimenuitem>Run Configure…</guimenuitem> and <guimenuitem>Build Project</guimenuitem> to be
- performed. It deletes all of the files generated by the build processes, including all the
- object files (<filename>*.o</filename> files), executable(s) and Makefiles. In other
- words, it leaves the project as though it has just been extracted from a distribution
- tarball.
- </para>
- <para>
- Choose the menu item <menuchoice><guisubmenu>Build</guisubmenu>
- <guimenuitem>Clean Project</guimenuitem></menuchoice> to completely clean the project.
- </para>
- </sect2>
- </sect1>
</chapter>
Modified: trunk/manuals/anjuta-manual/Makefile.am
==============================================================================
--- trunk/manuals/anjuta-manual/Makefile.am (original)
+++ trunk/manuals/anjuta-manual/Makefile.am Fri Aug 22 16:00:07 2008
@@ -4,7 +4,7 @@
DOC_ENTITIES = legal.xml debugger.xml introduction.xml projects.xml \
authors.xml legal.xml template.xml \
fileoperations.xml license.xml tools.xml \
- interface.xml preferences.xml
+ interface.xml preferences.xml build.xml
DOC_AM_CPPFLAGS =
DOC_FIGURES = figures/add_edit_macro.png \
figures/anjuta-in-action.png \
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
