From 5ca1a155de6776c48d75813f805ea116ced59227 Mon Sep 17 00:00:00 2001 From: Dirk Baechle Date: Mon, 12 Sep 2011 19:10:45 +0000 Subject: - Rollback of changes for revision 5355 (Additional chapter for User Guide, Basic steps) --- doc/user/MANIFEST | 1 - doc/user/depends.in | 2 +- doc/user/depends.xml | 2 +- doc/user/environments.in | 2 +- doc/user/environments.xml | 2 +- doc/user/hierarchy.in | 2 +- doc/user/hierarchy.xml | 2 +- doc/user/main.in | 5 -- doc/user/main.xml | 6 -- doc/user/simple.in | 4 +- doc/user/simple.xml | 4 +- doc/user/start.in | 196 ---------------------------------------------- doc/user/start.xml | 196 ---------------------------------------------- 13 files changed, 10 insertions(+), 414 deletions(-) delete mode 100644 doc/user/start.in delete mode 100644 doc/user/start.xml diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index 3f9eda3..0994f2b 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -40,7 +40,6 @@ 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 de5eb42..88828fe 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -914,7 +914,7 @@ -
+
Implicit Dependencies: The &cv-CPPPATH; Construction Variable diff --git a/doc/user/depends.xml b/doc/user/depends.xml index c423172..a5e84d6 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -903,7 +903,7 @@
-
+
Implicit Dependencies: The &cv-CPPPATH; Construction Variable diff --git a/doc/user/environments.in b/doc/user/environments.in index e74ffac..f767676 100644 --- a/doc/user/environments.in +++ b/doc/user/environments.in @@ -1095,7 +1095,7 @@ environment, of directory names, suffixes, etc.
-
+
Making Copies of &ConsEnvs;: the &Clone; Method diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 73d84d3..b2a8505 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -1089,7 +1089,7 @@ environment, of directory names, suffixes, etc.
-
+
Making Copies of &ConsEnvs;: the &Clone; Method diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index b423465..d70633d 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -478,7 +478,7 @@ make no difference to the build.
-
+
Sharing Environments (and Other Variables) Between &SConscript; Files diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index baf8065..2e2941c 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -442,7 +442,7 @@ make no difference to the build.
-
+
Sharing Environments (and Other Variables) Between &SConscript; Files diff --git a/doc/user/main.in b/doc/user/main.in index 2e3683f..4b0807d 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -152,11 +152,6 @@ &build-install; - - Basic steps and advice - &start; - - Simple Builds &simple; diff --git a/doc/user/main.xml b/doc/user/main.xml index ccc3208..4b0807d 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -85,7 +85,6 @@ - @@ -153,11 +152,6 @@ &build-install; - - Basic steps and advice - &start; - - Simple Builds &simple; diff --git a/doc/user/simple.in b/doc/user/simple.in index 373d2b8..8a25be5 100644 --- a/doc/user/simple.in +++ b/doc/user/simple.in @@ -297,7 +297,7 @@
-
+
The &SConstruct; File @@ -353,7 +353,7 @@
-
+
&SCons; Functions Are Order-Independent diff --git a/doc/user/simple.xml b/doc/user/simple.xml index e24ecbd..2a687a0 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -322,7 +322,7 @@
-
+
The &SConstruct; File @@ -378,7 +378,7 @@
-
+
&SCons; Functions Are Order-Independent diff --git a/doc/user/start.in b/doc/user/start.in deleted file mode 100644 index 3d1693b..0000000 --- a/doc/user/start.in +++ /dev/null @@ -1,196 +0,0 @@ - - - - -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. - - - -
- SCons files - -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...). - - -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. - - -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 ), at the top of your source folder tree: - - -yoursrc - yourlib1 - *.cpp/h - yourlib2 - *.cpp/h - yourexe - *.cpp/h - README - INSTALL - SConstruct - - -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 ), you call the command - - - % scons - - -and the processing starts. &SCons; reads your &SConstruct; and starts to build things for you, hopefully. - - -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... - - -
- -
- A few additional guidelines - - - 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. - - - - - - Think in modules: 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. - - - 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. - - -A simple example: - - -yoursrc - yourlib1 - SConscript - *.cpp/h - yourlib2 - SConscript - *.cpp/h - SConstruct - - -would include the &SConscript;s by - - -SConscript(['yourlib1/SConscript']) -SConscript(['yourlib2/SConscript']) - - -in the &SConstruct;. - -Check out and for more infos about this. - - - - - Configure at the top and reuse: 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. - - - In your &SConstruct; at the top you can create and export a basic Environment as: - -env = Environment(tools=['default'], CC='/opt/arm-gcc_4.01/bin/gcc') -Export('env') - - and access it in one of your &SConscript;s by: - -Import('env') -debug_env = env.Clone() -debug_env.Append(CCFLAGS=['-g']) -debug_env.Program('foo','foo.c') - - - -Pointers to more info are , -especially and -, as well as . - - - - Think in dependencies: &SCons; works by knowing dependencies. Internally, - it builds a large dependency - graph (DAG, directed acyclic graph) 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 make (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! - - - , , - , and - will tell you more about how dependencies work in &SCons; and can be bent - the way you want them. - - - - Don't serialize: 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 A and B in a predefined sequence (cf. ). - 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. - - - &SCons; supports building multiple targets in parallel via a -j option that - takes, as its argument, the number of simultaneous tasks that may be - spawned: scons -j 4 builds four targets - in parallel, for example. - - - - -
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 @@ - - - - -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. - - - -
- SCons files - -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...). - - -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. - - -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 ), at the top of your source folder tree: - - -yoursrc - yourlib1 - *.cpp/h - yourlib2 - *.cpp/h - yourexe - *.cpp/h - README - INSTALL - SConstruct - - -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 ), you call the command - - - % scons - - -and the processing starts. &SCons; reads your &SConstruct; and starts to build things for you, hopefully. - - -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... - - -
- -
- A few additional guidelines - - - 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. - - - - - - Think in modules: 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. - - - 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. - - -A simple example: - - -yoursrc - yourlib1 - SConscript - *.cpp/h - yourlib2 - SConscript - *.cpp/h - SConstruct - - -would include the &SConscript;s by - - -SConscript(['yourlib1/SConscript']) -SConscript(['yourlib2/SConscript']) - - -in the &SConstruct;. - -Check out and for more infos about this. - - - - - Configure at the top and reuse: 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. - - - In your &SConstruct; at the top you can create and export a basic Environment as: - -env = Environment(tools=['default'], CC='/opt/arm-gcc_4.01/bin/gcc') -Export('env') - - and access it in one of your &SConscript;s by: - -Import('env') -debug_env = env.Clone() -debug_env.Append(CCFLAGS=['-g']) -debug_env.Program('foo','foo.c') - - - -Pointers to more info are , -especially and -, as well as . - - - - Think in dependencies: &SCons; works by knowing dependencies. Internally, - it builds a large dependency - graph (DAG, directed acyclic graph) 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 make (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! - - - , , - , and - will tell you more about how dependencies work in &SCons; and can be bent - the way you want them. - - - - Don't serialize: 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 A and B in a predefined sequence (cf. ). - 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. - - - &SCons; supports building multiple targets in parallel via a -j option that - takes, as its argument, the number of simultaneous tasks that may be - spawned: scons -j 4 builds four targets - in parallel, for example. - - - - -
-- cgit v0.12