diff options
Diffstat (limited to 'doc/user/start.xml')
| -rw-r--r-- | doc/user/start.xml | 196 |
1 files changed, 0 insertions, 196 deletions
diff --git a/doc/user/start.xml b/doc/user/start.xml deleted file mode 100644 index 3d1693b..0000000 --- a/doc/user/start.xml +++ /dev/null @@ -1,196 +0,0 @@ -<!-- - - __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> |