diff options
Diffstat (limited to 'doc/user')
| -rw-r--r-- | doc/user/MANIFEST | 1 | ||||
| -rw-r--r-- | doc/user/depends.in | 2 | ||||
| -rw-r--r-- | doc/user/depends.xml | 2 | ||||
| -rw-r--r-- | doc/user/environments.in | 2 | ||||
| -rw-r--r-- | doc/user/environments.xml | 2 | ||||
| -rw-r--r-- | doc/user/hierarchy.in | 2 | ||||
| -rw-r--r-- | doc/user/hierarchy.xml | 2 | ||||
| -rw-r--r-- | doc/user/main.in | 5 | ||||
| -rw-r--r-- | doc/user/main.xml | 6 | ||||
| -rw-r--r-- | doc/user/simple.in | 4 | ||||
| -rw-r--r-- | doc/user/simple.xml | 4 | ||||
| -rw-r--r-- | doc/user/start.in | 196 | ||||
| -rw-r--r-- | doc/user/start.xml | 196 |
13 files changed, 414 insertions, 10 deletions
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index 0994f2b..3f9eda3 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -40,6 +40,7 @@ sconf.xml separate.xml simple.xml sourcecode.xml +start.xml tasks.xml tools.xml troubleshoot.xml diff --git a/doc/user/depends.in b/doc/user/depends.in index 88828fe..de5eb42 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -914,7 +914,7 @@ </section> - <section> + <section id="sect-implicit-dependencies"> <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> diff --git a/doc/user/depends.xml b/doc/user/depends.xml index a5e84d6..c423172 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -903,7 +903,7 @@ </section> - <section> + <section id="sect-implicit-dependencies"> <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> diff --git a/doc/user/environments.in b/doc/user/environments.in index f767676..e74ffac 100644 --- a/doc/user/environments.in +++ b/doc/user/environments.in @@ -1095,7 +1095,7 @@ environment, of directory names, suffixes, etc. </section> - <section> + <section id="sect-clone-environments"> <title>Making Copies of &ConsEnvs;: the &Clone; Method</title> <para> diff --git a/doc/user/environments.xml b/doc/user/environments.xml index b2a8505..73d84d3 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -1089,7 +1089,7 @@ environment, of directory names, suffixes, etc. </section> - <section> + <section id="sect-clone-environments"> <title>Making Copies of &ConsEnvs;: the &Clone; Method</title> <para> diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index d70633d..b423465 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -478,7 +478,7 @@ make no difference to the build. </section> - <section> + <section id="sect-sharing-environments"> <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title> <para> diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index 2e2941c..baf8065 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -442,7 +442,7 @@ make no difference to the build. </section> - <section> + <section id="sect-sharing-environments"> <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title> <para> diff --git a/doc/user/main.in b/doc/user/main.in index 4b0807d..2e3683f 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -152,6 +152,11 @@ &build-install; </chapter> + <chapter id="chap-start"> + <title>Basic steps and advice</title> + &start; + </chapter> + <chapter id="chap-simple"> <title>Simple Builds</title> &simple; diff --git a/doc/user/main.xml b/doc/user/main.xml index 4b0807d..ccc3208 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -85,6 +85,7 @@ <!ENTITY sconf SYSTEM "sconf.xml"> <!ENTITY separate SYSTEM "separate.xml"> <!ENTITY simple SYSTEM "simple.xml"> + <!ENTITY start SYSTEM "start.xml"> <!ENTITY sourcecode SYSTEM "sourcecode.xml"> <!ENTITY tasks SYSTEM "tasks.xml"> <!ENTITY tools SYSTEM "tools.xml"> @@ -152,6 +153,11 @@ &build-install; </chapter> + <chapter id="chap-start"> + <title>Basic steps and advice</title> + &start; + </chapter> + <chapter id="chap-simple"> <title>Simple Builds</title> &simple; diff --git a/doc/user/simple.in b/doc/user/simple.in index 8a25be5..373d2b8 100644 --- a/doc/user/simple.in +++ b/doc/user/simple.in @@ -297,7 +297,7 @@ </section> - <section> + <section id="sect-sconstruct-file"> <title>The &SConstruct; File</title> <para> @@ -353,7 +353,7 @@ </section> - <section> + <section id="sect-order-independent"> <title>&SCons; Functions Are Order-Independent</title> <para> diff --git a/doc/user/simple.xml b/doc/user/simple.xml index 2a687a0..e24ecbd 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -322,7 +322,7 @@ </section> - <section> + <section id="sect-sconstruct-file"> <title>The &SConstruct; File</title> <para> @@ -378,7 +378,7 @@ </section> - <section> + <section id="sect-order-independent"> <title>&SCons; Functions Are Order-Independent</title> <para> diff --git a/doc/user/start.in b/doc/user/start.in new file mode 100644 index 0000000..3d1693b --- /dev/null +++ b/doc/user/start.in @@ -0,0 +1,196 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + +If you're completely new to a build system like &SCons;, this chapter is written for you. +We very briefly discuss the general setup of your project, regarding the &SCons; configuration +files &SConstruct; and &SConscript;. +Additionally, a few guidelines are provided about how to start a project...hopefully preventing you from +running into dead-end after dead-end later on. + + </para> + + <section> + <title>SCons files</title> + <para> +Okay, so you have a version of your shiny new project, ready for its very first &SCons; build. Or maybe you decided +to drop make/autotools, and want to try out &SCons; on the cool media-message-mailing library that you already provide +on Sourceforge (Tigris, Github, Bitbucket, Launchpad...). +</para> +<para> +Let's say you have a source folder in your file system, a directory with all the input files for the build process. +These may be C or C++ files, TeX/LaTeX sources or a Java package tree. For a start we also assume that you want the +resulting files, like libs, executables, JARs and PDFs, to be created in the same folder structure. Alongside your +sources, so to speak. +</para> +<para> +In order to get &SCons; going you have to give it your input files and tell it what to build. Like in most build systems, +this is done by writing a special text file (or several of them) further describing your build setup. You place this +file, named &SConstruct; (see <xref linkend="chap-simple"></xref>), at the top of your source folder tree: +</para> +<screen> +yoursrc + yourlib1 + *.cpp/h + yourlib2 + *.cpp/h + yourexe + *.cpp/h + README + INSTALL + SConstruct +</screen> +<para> +To start a build, you open a terminal (text console, prompt, shell,...whatever it is called in your current system) and +change into the folder with the &SConstruct; in it. Having &SCons; properly installed (see <xref linkend="chap-build-install"></xref>), you call the command +</para> + <screen> + % <userinput>scons</userinput> + </screen> +<para> +and the processing starts. &SCons; reads your &SConstruct; and starts to build things for you, hopefully. +</para> +<para> +So much for a very quick start and the basics about how to get &SCons; going. +A discussion of &SCons; at great length can be found in the following +chapters and sections. Read on please, to learn more about all the available features and possibilities... +</para> + + </section> + + <section> + <title>A few additional guidelines</title> + + <para> + With &SCons; and the power of Python as backup, you are pretty much free to do anything + you like. However, when you start without any prior experience a few pointers might + help as a good foundation for your work. That's exactly what the following list is there + for. A few best practices and you can have your pick...or roll your own stuff. + </para> + + <itemizedlist> + + <listitem> + <para><emphasis>Think in modules</emphasis>: Try to create an &SConscript; for + each subfolder, containing one of your libs or executables. + Then, call these &SConscript;s from a single &SConstruct; at the top of your + build directory. + </para> + <para> + From what our experience tells us, this is the setup that offers you the most flexibility + regarding build options and variant dirs. It may look a bit complicated and overdone + right now, but starting this way pays off really fast. + </para> + <para> +A simple example: + </para> + <screen> +yoursrc + yourlib1 + SConscript + *.cpp/h + yourlib2 + SConscript + *.cpp/h + SConstruct +</screen> +<para> +would include the &SConscript;s by +</para> +<screen> +SConscript(['yourlib1/SConscript']) +SConscript(['yourlib2/SConscript']) +</screen> +<para> +in the &SConstruct;. +</para> +<para>Check out <xref linkend="sect-sconstruct-file"></xref> and <xref linkend="chap-hierarchical"></xref> for more infos about this. +</para> + </listitem> + + <listitem> + <para><emphasis>Configure at the top and reuse</emphasis>: Configure the environments that you + need, in your &SConstruct; file at the very top of your build tree. + Don't create them anew in each &SConscript; (module) but export them globally + and use Clone() to make a local copy where required. + </para> + <para> + In your &SConstruct; at the top you can create and export a basic Environment as: +<screen> +env = Environment(tools=['default'], CC='/opt/arm-gcc_4.01/bin/gcc') +Export('env') +</screen> + and access it in one of your &SConscript;s by: +<screen> +Import('env') +debug_env = env.Clone() +debug_env.Append(CCFLAGS=['-g']) +debug_env.Program('foo','foo.c') +</screen> +</para> +<para> +Pointers to more info are <xref linkend="chap-environments"></xref>, +especially <xref linkend="sect-construction-environments"></xref> and +<xref linkend="sect-clone-environments"></xref>, as well as <xref linkend="sect-sharing-environments"></xref>. + </para> + </listitem> + <listitem> + <para><emphasis>Think in dependencies</emphasis>: &SCons; works by knowing dependencies. Internally, + it builds a large dependency + graph (DAG, <emphasis>directed acyclic graph</emphasis>) for all its build tasks. The single + files are managed as nodes, while the edges represent the build dependencies. + No dependency, no build. It's that simple. + Try to forget about those phony targets, that you may have used all throughout <literal>make</literal> (shudder). + Check out this User manual, or ask for help on the &SCons; mailing lists. Don't fall back to those + bad old habits and hack around, only because you're under time pressure. Try to do your builds the &SCons; way! + </para> + <para> + <xref linkend="chap-depends"></xref>, <xref linkend="sect-implicit-dependencies"></xref>, + <xref linkend="chap-builders-writing"></xref>, and <xref linkend="chap-scanners"></xref> + will tell you more about how dependencies work in &SCons; and can be bent + the way you want them. + </para> + </listitem> + <listitem> + <para><emphasis>Don't serialize</emphasis>: Finally, &SCons; is all about handling large projects with complicated builds. It is specially + optimized for working in parallel, and schedules all the single build tasks automatically. + This means that you can't easily get &SCons; to execute some scripts <literal>A</literal> and <literal>B</literal> in a predefined sequence (cf. <xref linkend="sect-order-independent"></xref>). + If you want to define a simple series of build tasks, that have to get executed in a fixed order regardless + of dependencies and timestamps, you should consider to use a simple shell or Python script as + wrapper instead. + Don't hurt your brain, while trying to force &SCons; into doing something that it wasn't designed for in the + first place. + </para> + <para> + &SCons; supports building multiple targets in parallel via a <literal>-j</literal> option that + takes, as its argument, the number of simultaneous tasks that may be + spawned: <quote><literal>scons -j 4</literal></quote> builds four targets + in parallel, for example. + </para> + </listitem> + </itemizedlist> + + </section> diff --git a/doc/user/start.xml b/doc/user/start.xml new file mode 100644 index 0000000..3d1693b --- /dev/null +++ b/doc/user/start.xml @@ -0,0 +1,196 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + +If you're completely new to a build system like &SCons;, this chapter is written for you. +We very briefly discuss the general setup of your project, regarding the &SCons; configuration +files &SConstruct; and &SConscript;. +Additionally, a few guidelines are provided about how to start a project...hopefully preventing you from +running into dead-end after dead-end later on. + + </para> + + <section> + <title>SCons files</title> + <para> +Okay, so you have a version of your shiny new project, ready for its very first &SCons; build. Or maybe you decided +to drop make/autotools, and want to try out &SCons; on the cool media-message-mailing library that you already provide +on Sourceforge (Tigris, Github, Bitbucket, Launchpad...). +</para> +<para> +Let's say you have a source folder in your file system, a directory with all the input files for the build process. +These may be C or C++ files, TeX/LaTeX sources or a Java package tree. For a start we also assume that you want the +resulting files, like libs, executables, JARs and PDFs, to be created in the same folder structure. Alongside your +sources, so to speak. +</para> +<para> +In order to get &SCons; going you have to give it your input files and tell it what to build. Like in most build systems, +this is done by writing a special text file (or several of them) further describing your build setup. You place this +file, named &SConstruct; (see <xref linkend="chap-simple"></xref>), at the top of your source folder tree: +</para> +<screen> +yoursrc + yourlib1 + *.cpp/h + yourlib2 + *.cpp/h + yourexe + *.cpp/h + README + INSTALL + SConstruct +</screen> +<para> +To start a build, you open a terminal (text console, prompt, shell,...whatever it is called in your current system) and +change into the folder with the &SConstruct; in it. Having &SCons; properly installed (see <xref linkend="chap-build-install"></xref>), you call the command +</para> + <screen> + % <userinput>scons</userinput> + </screen> +<para> +and the processing starts. &SCons; reads your &SConstruct; and starts to build things for you, hopefully. +</para> +<para> +So much for a very quick start and the basics about how to get &SCons; going. +A discussion of &SCons; at great length can be found in the following +chapters and sections. Read on please, to learn more about all the available features and possibilities... +</para> + + </section> + + <section> + <title>A few additional guidelines</title> + + <para> + With &SCons; and the power of Python as backup, you are pretty much free to do anything + you like. However, when you start without any prior experience a few pointers might + help as a good foundation for your work. That's exactly what the following list is there + for. A few best practices and you can have your pick...or roll your own stuff. + </para> + + <itemizedlist> + + <listitem> + <para><emphasis>Think in modules</emphasis>: Try to create an &SConscript; for + each subfolder, containing one of your libs or executables. + Then, call these &SConscript;s from a single &SConstruct; at the top of your + build directory. + </para> + <para> + From what our experience tells us, this is the setup that offers you the most flexibility + regarding build options and variant dirs. It may look a bit complicated and overdone + right now, but starting this way pays off really fast. + </para> + <para> +A simple example: + </para> + <screen> +yoursrc + yourlib1 + SConscript + *.cpp/h + yourlib2 + SConscript + *.cpp/h + SConstruct +</screen> +<para> +would include the &SConscript;s by +</para> +<screen> +SConscript(['yourlib1/SConscript']) +SConscript(['yourlib2/SConscript']) +</screen> +<para> +in the &SConstruct;. +</para> +<para>Check out <xref linkend="sect-sconstruct-file"></xref> and <xref linkend="chap-hierarchical"></xref> for more infos about this. +</para> + </listitem> + + <listitem> + <para><emphasis>Configure at the top and reuse</emphasis>: Configure the environments that you + need, in your &SConstruct; file at the very top of your build tree. + Don't create them anew in each &SConscript; (module) but export them globally + and use Clone() to make a local copy where required. + </para> + <para> + In your &SConstruct; at the top you can create and export a basic Environment as: +<screen> +env = Environment(tools=['default'], CC='/opt/arm-gcc_4.01/bin/gcc') +Export('env') +</screen> + and access it in one of your &SConscript;s by: +<screen> +Import('env') +debug_env = env.Clone() +debug_env.Append(CCFLAGS=['-g']) +debug_env.Program('foo','foo.c') +</screen> +</para> +<para> +Pointers to more info are <xref linkend="chap-environments"></xref>, +especially <xref linkend="sect-construction-environments"></xref> and +<xref linkend="sect-clone-environments"></xref>, as well as <xref linkend="sect-sharing-environments"></xref>. + </para> + </listitem> + <listitem> + <para><emphasis>Think in dependencies</emphasis>: &SCons; works by knowing dependencies. Internally, + it builds a large dependency + graph (DAG, <emphasis>directed acyclic graph</emphasis>) for all its build tasks. The single + files are managed as nodes, while the edges represent the build dependencies. + No dependency, no build. It's that simple. + Try to forget about those phony targets, that you may have used all throughout <literal>make</literal> (shudder). + Check out this User manual, or ask for help on the &SCons; mailing lists. Don't fall back to those + bad old habits and hack around, only because you're under time pressure. Try to do your builds the &SCons; way! + </para> + <para> + <xref linkend="chap-depends"></xref>, <xref linkend="sect-implicit-dependencies"></xref>, + <xref linkend="chap-builders-writing"></xref>, and <xref linkend="chap-scanners"></xref> + will tell you more about how dependencies work in &SCons; and can be bent + the way you want them. + </para> + </listitem> + <listitem> + <para><emphasis>Don't serialize</emphasis>: Finally, &SCons; is all about handling large projects with complicated builds. It is specially + optimized for working in parallel, and schedules all the single build tasks automatically. + This means that you can't easily get &SCons; to execute some scripts <literal>A</literal> and <literal>B</literal> in a predefined sequence (cf. <xref linkend="sect-order-independent"></xref>). + If you want to define a simple series of build tasks, that have to get executed in a fixed order regardless + of dependencies and timestamps, you should consider to use a simple shell or Python script as + wrapper instead. + Don't hurt your brain, while trying to force &SCons; into doing something that it wasn't designed for in the + first place. + </para> + <para> + &SCons; supports building multiple targets in parallel via a <literal>-j</literal> option that + takes, as its argument, the number of simultaneous tasks that may be + spawned: <quote><literal>scons -j 4</literal></quote> builds four targets + in parallel, for example. + </para> + </listitem> + </itemizedlist> + + </section> |