From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- doc/user/simple.in | 517 ----------------------------------------------------- 1 file changed, 517 deletions(-) delete mode 100644 doc/user/simple.in (limited to 'doc/user/simple.in') diff --git a/doc/user/simple.in b/doc/user/simple.in deleted file mode 100644 index 76b044b..0000000 --- a/doc/user/simple.in +++ /dev/null @@ -1,517 +0,0 @@ - - - - - In this chapter, - you will see several examples of - very simple build configurations using &SCons;, - which will demonstrate how easy - it is to use &SCons; to - build programs from several different programming languages - on different types of systems. - - - -
- Building Simple C / C++ Programs - - - - Here's the famous "Hello, World!" program in C: - - - - - int - main() - { - printf("Hello, world!\n"); - } - - - - - And here's how to build it using &SCons;. - Enter the following into a file named &SConstruct;: - - - - - - Program('hello.c') - - - int main() { printf("Hello, world!\n"); } - - - - - - This minimal configuration file gives - &SCons; two pieces of information: - what you want to build - (an executable program), - and the input file from - which you want it built - (the hello.c file). - &b-link-Program; is a builder_method, - a Python call that tells &SCons; that you want to build an - executable program. - - - - - - That's it. Now run the &scons; command to build the program. - On a POSIX-compliant system like Linux or UNIX, - you'll see something like: - - - - - scons - - - - - On a Windows system with the Microsoft Visual C++ compiler, - you'll see something like: - - - - - scons - - - - - First, notice that you only need - to specify the name of the source file, - and that &SCons; correctly deduces the names of - the object and executable files to be built - from the base of the source file name. - - - - - - Second, notice that the same input &SConstruct; file, - without any changes, - generates the correct output file names on both systems: - hello.o and hello - on POSIX systems, - hello.obj and hello.exe - on Windows systems. - This is a simple example of how &SCons; - makes it extremely easy to - write portable software builds. - - - - - - (Note that we won't provide duplicate side-by-side - POSIX and Windows output for all of the examples in this guide; - just keep in mind that, unless otherwise specified, - any of the examples should work equally well on both types of systems.) - - - -
- -
- Building Object Files - - - - The &b-link-Program; builder method is only one of - many builder methods that &SCons; provides - to build different types of files. - Another is the &b-link-Object; builder method, - which tells &SCons; to build an object file - from the specified source file: - - - - - - Object('hello.c') - - - int main() { printf("Hello, world!\n"); } - - - - - - Now when you run the &scons; command to build the program, - it will build just the &hello_o; object file on a POSIX system: - - - - - scons - - - - - And just the &hello_obj; object file - on a Windows system (with the Microsoft Visual C++ compiler): - - - - - scons - - -
- -
- Simple Java Builds - - - - &SCons; also makes building with Java extremely easy. - Unlike the &b-link-Program; and &b-link-Object; builder methods, - however, the &b-link-Java; builder method - requires that you specify - the name of a destination directory in which - you want the class files placed, - followed by the source directory - in which the .java files live: - - - - - - Java('classes', 'src') - - - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - - - - - - If the src directory - contains a single hello.java file, - then the output from running the &scons; command - would look something like this - (on a POSIX system): - - - - - scons - - - - - We'll cover Java builds in more detail, - including building Java archive (.jar) - and other types of file, - in . - - - -
- -
- Cleaning Up After a Build - - - - When using &SCons;, it is unnecessary to add special - commands or target names to clean up after a build. - Instead, you simply use the - -c or --clean - option when you invoke &SCons;, - and &SCons; removes the appropriate built files. - So if we build our example above - and then invoke scons -c - afterwards, the output on POSIX looks like: - - - - - - Program('hello.c') - - - int main() { printf("Hello, world!\n"); } - - - - - scons - scons -c - - - - - And the output on Windows looks like: - - - - - scons - scons -c - - - - - Notice that &SCons; changes its output to tell you that it - is Cleaning targets ... and - done cleaning targets. - - - -
- -
- The &SConstruct; File - - - - If you're used to build systems like &Make; - you've already figured out that the &SConstruct; file - is the &SCons; equivalent of a &Makefile;. - That is, the &SConstruct; file is the input file - that &SCons; reads to control the build. - - - -
- &SConstruct; Files Are Python Scripts - - - - There is, however, an important difference between - an &SConstruct; file and a &Makefile;: - the &SConstruct; file is actually a Python script. - If you're not already familiar with Python, don't worry. - This User's Guide will introduce you step-by-step - to the relatively small amount of Python you'll - need to know to be able to use &SCons; effectively. - And Python is very easy to learn. - - - - - - One aspect of using Python as the - scripting language is that you can put comments - in your &SConstruct; file using Python's commenting convention; - that is, everything between a '#' and the end of the line - will be ignored: - - - - - # Arrange to build the "hello" program. - Program('hello.c') # "hello.c" is the source file. - - - - - You'll see throughout the remainder of this Guide - that being able to use the power of a - real scripting language - can greatly simplify the solutions - to complex requirements of real-world builds. - - - -
- -
- &SCons; Functions Are Order-Independent - - - - One important way in which the &SConstruct; - file is not exactly like a normal Python script, - and is more like a &Makefile;, - is that the order in which - the &SCons; functions are called in - the &SConstruct; file - does not - affect the order in which &SCons; - actually builds the programs and object files - you want it to build. - In programming parlance, - the &SConstruct; file is - declarative, - meaning you tell &SCons; what you want done - and let it figure out the order in which to do it, - rather than strictly imperative, - where you specify explicitly the order in - which to do things. - - - In other words, when you call the &b-link-Program; builder - (or any other builder method), - you're not telling &SCons; to build - the program at the instant the builder method is called. - Instead, you're telling &SCons; to build the program - that you want, for example, - a program built from a file named &hello_c;, - and it's up to &SCons; to build that program - (and any other files) whenever it's necessary. - (We'll learn more about how - &SCons; decides when building or rebuilding a file - is necessary in , below.) - - - - - - &SCons; reflects this distinction between - calling a builder method like &b-Program; - and actually building the program - by printing the status messages that indicate - when it's "just reading" the &SConstruct; file, - and when it's actually building the target files. - This is to make it clear when &SCons; is - executing the Python statements that make up the &SConstruct; file, - and when &SCons; is actually executing the - commands or other actions to - build the necessary files. - - - - - - Let's clarify this with an example. - Python has a print statement that - prints a string of characters to the screen. - If we put print statements around - our calls to the &b-Program; builder method: - - - - - - print "Calling Program('hello.c')" - Program('hello.c') - print "Calling Program('goodbye.c')" - Program('goodbye.c') - print "Finished calling Program()" - - - int main() { printf("Hello, world!\n"); } - - - int main() { printf("Goodbye, world!\n"); } - - - - - - Then when we execute &SCons;, - we see the output from the print - statements in between the messages about - reading the &SConscript; files, - indicating that that is when the - Python statements are being executed: - - - - - scons - - - - - Notice also that &SCons; built the &goodbye; program first, - even though the "reading &SConscript;" output - shows that we called Program('hello.c') - first in the &SConstruct; file. - - - -
- -
- -
- Making the &SCons; Output Less Verbose - - - - You've already seen how &SCons; prints - some messages about what it's doing, - surrounding the actual commands used to build the software: - - - - - scons - - - - - These messages emphasize the - order in which &SCons; does its work: - all of the configuration files - (generically referred to as &SConscript; files) - are read and executed first, - and only then are the target files built. - Among other benefits, these messages help to distinguish between - errors that occur while the configuration files are read, - and errors that occur while targets are being built. - - - - - - One drawback, of course, is that these messages clutter the output. - Fortunately, they're easily disabled by using - the &Q; option when invoking &SCons;: - - - - - scons -Q - - - - - Because we want this User's Guide to focus - on what &SCons; is actually doing, - we're going to use the &Q; option - to remove these messages from the - output of all the remaining examples in this Guide. - - - -
-- cgit v1.2.3