Standardize license header on in-use doc files [skip appveyor]

[scons.git] / doc / user / simple.xml

<?xml version='1.0'?>

<!--
SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
SPDX-License-Identifier: MIT
SPDX-FileType: DOCUMENTATION

This file is processed by the bin/SConsDoc.py module.
-->

<!DOCTYPE sconsdoc [
    <!ENTITY % scons SYSTEM "../scons.mod">
    %scons;

    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
    %builders-mod;
    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
    %functions-mod;
    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
    %tools-mod;
    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
    %variables-mod;
]>

<chapter id="chap-simple"
         xmlns="http://www.scons.org/dbxsd/v1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<title>Simple Builds</title>

 <para>

 The single most important thing you do when writing a
 build system for your project is to describe the "what":
 what you want to build, and which files you want to build it from.
 And, in fact, simpler builds may need no more.
 In this chapter, you will see several examples of
 very simple build configurations using &SCons;,
 which will demonstrate how easy &SCons; makes it to
 build programs on different types of systems.

 </para>

 <section id="sect-build-simple">
 <title>Building Simple C / C++ Programs</title>

   <para>

   Here's the ubiquitous
   <ulink url="https://en.wikipedia.org/wiki/%22Hello,_World!%22_program">
   "Hello, World!"</ulink> program in C:

   </para>

   <programlisting>
#include &lt;stdio.h&gt;

int
main()
{
        printf("Hello, world!\n");
}
   </programlisting>

   <para>

   And here's how to build it using &SCons;.
   Save the code above into <filename>hello.c</filename>,
   and enter the following into a file named &SConstruct;:

   </para>

   <scons_example name="simple_ex1">
      <file name="SConstruct" printme="1">
Program('hello.c')
      </file>
      <file name="hello.c">
int main() { printf("Hello, world!\n"); }
      </file>
   </scons_example>

   <para>

   This minimal build file gives
   &SCons; three key pieces of information:
   what you want to build (a program);
   what you want to call that program (its
   base name will be <filename>hello</filename>),
   and the source file you want it built from
   (the <filename>hello.c</filename> file).
   &b-link-Program; is a <firstterm>&Builder;</firstterm>,
   an &SCons; function that you use to instruct
   &SCons; about the "what" of your build.

   </para>

   <para>

   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:

   </para>

   <scons_output example="simple_ex1" os="posix" suffix="1">
      <scons_output_command>scons</scons_output_command>
   </scons_output>

   <para>

   On a Windows system with the &MSVC; compiler,
   you'll see something like:

   </para>

   <scons_output example="simple_ex1" os="win32" suffix="2">
      <scons_output_command>scons</scons_output_command>
   </scons_output>

   <para>

   Notice that &SCons; deduced quite a bit here: it figured
   out the name of the program to build, including operating
   system specific suffixes (&hello; or &hello_exe;), based off
   the basename of the source file; it knows an intermediate
   object file should be built (&hello_o; or &hello_obj;);
   and it knows how to build those things using the compiler
   that is appropriate on the system you're using.
   It was not necessary to instruct &SCons; about any of those
   details.
   This is an example of how &SCons;
   makes it easy to write portable software builds.

   </para>

   <para>

   For the programming languages &SCons; already knows about,
   it will mostly just figure it out.
   Here's the "Hello, World!" example in Fortran:

   </para>

   <programlisting>
program hello
  print *, 'Hello, World!'
end program hello
   </programlisting>

   <sconstruct>
Program('hello', 'hello.f90')
   </sconstruct>

   <!--  # SConsExample doesn't speak Fortran, will show as "cc"
   <scons_example name="simple_ex1f">
      <file name="SConstruct" printme="1">
Program('hello', 'hello.f90')
      </file>
      <file name="hello.f90">
program hello
  print *, 'Hello, World!'
end program hello
      </file>
   </scons_example>

   <scons_output example="simple_ex1f" os="posix" suffix="1">
      <scons_output_command>scons</scons_output_command>
   </scons_output-->

   <!-- so just hardcode it: -->
   <screen>
$ <userinput>scons</userinput>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
gfortran -o hello.o -c hello.f90
gfortran -o hello hello.o
scons: done building targets.
   </screen>

 </section>

 <section id="sect-building-object">
 <title>Building Object Files</title>

   <para>

   The &b-link-Program; builder is only one of
   many builders (also called a <firstterm>&builder_method;</firstterm>)
   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:

   </para>

   <scons_example name="simple_Object">
      <file name="SConstruct" printme="1">
Object('hello.c')
      </file>
      <file name="hello.c">
int main() { printf("Hello, world!\n"); }
      </file>
   </scons_example>

   <para>

   Now when you run the &scons; command to build the program,
   it will build just the &hello_o; object file on a POSIX system:

   </para>

   <scons_output example="simple_Object" os="posix" suffix="1">
      <scons_output_command>scons</scons_output_command>
   </scons_output>

   <para>

   And just the &hello_obj; object file
   on a Windows system (with the &MSVC; compiler):

   </para>

   <scons_output example="simple_Object" os="win32" suffix="2">
      <scons_output_command>scons</scons_output_command>
   </scons_output>

   <para>

   (Note that this guide will not continue to provide duplicate side-by-side
   POSIX and Windows output for all of the examples.
   Just keep in mind that, unless otherwise specified,
   any of the examples should work equally well on both types of systems.)

   </para>

 </section>

 <section id="sect-building-java">
 <title>Simple Java Builds</title>

   <para>

   &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 <filename>.java</filename> files live:

   </para>

   <scons_example name="simple_java">
     <file name="SConstruct" printme="1">
Java('classes', 'src')
     </file>
     <file name="src/hello.java">
public class Example1
{
  public static void main(String[] args)
  {
    System.out.println("Hello Java world!\n");
  }
}
     </file>
   </scons_example>

   <para>

   If the <filename>src</filename> directory
   contains a single <filename>hello.java</filename> file,
   then the output from running the &scons; command
   would look something like this
   (on a POSIX system):

   </para>

   <scons_output example="simple_java" os="posix" suffix="1">
      <scons_output_command>scons</scons_output_command>
   </scons_output>

   <para>

   Java builds will be covered in much more detail,
   including building a Java archive (<filename>.jar</filename>)
   and other types of files,
   in <xref linkend="chap-java"></xref>.

   </para>

 </section>

 <section id="sect-building-clean">
 <title>Cleaning Up After a Build</title>

   <para>

   For cleaning up your build tree, &SCons; provides a
   "clean" mode, selected by the
   <option>-c</option> or <option>--clean</option>
   option when you invoke &SCons;.
   &SCons; selects the same set of targets it would in build mode,
   but instead of building, removes them.
   That means you can control what is cleaned
   in exactly the same way as you control what gets built.
   If you build the C example above
   and then invoke <userinput>scons -c</userinput>
   afterwards, the output on POSIX looks like:

   </para>

   <scons_example name="simple_clean">
      <file name="SConstruct">
Program('hello.c')
      </file>
      <file name="hello.c">
int main() { printf("Hello, world!\n"); }
      </file>
   </scons_example>

   <scons_output example="simple_clean" os="posix" suffix="1">
      <scons_output_command>scons</scons_output_command>
      <scons_output_command>scons -c</scons_output_command>
   </scons_output>

   <para>

   And the output on Windows looks like:

   </para>

   <scons_output example="simple_clean" os="win32" suffix="2">
      <scons_output_command>scons</scons_output_command>
      <scons_output_command>scons -c</scons_output_command>
   </scons_output>

   <para>

   Notice that &SCons; changes its output to tell you that it
   is <computeroutput>Cleaning targets ...</computeroutput> and
   <computeroutput>done cleaning targets.</computeroutput>

   </para>

 </section>

 <section id="sect-sconstruct-file">
 <title>The &SConstruct; File</title>

   <para>

   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.

   </para>

   <section id="sect-sconstruct-python">
   <title>&SConstruct; Files Are Python Scripts</title>

     <para>

     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.

     </para>

     <para>

     One aspect of using &Python; as the
     scripting language is that you can put comments
     in your &SConstruct; file using &Python;'s commenting convention:
     everything between a <literal>#</literal> character
     and the end of the line will be ignored
     (unless the character appears inside a string constant).

     </para>

     <sconstruct>
# Arrange to build the "hello" program.
Program("hello.c")    # "hello.c" is the source file.
Program("#goodbye.c") # the # in "#goodbye" does not indicate a comment
     </sconstruct>

     <para>

     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.

     </para>

   </section>

   <section id="sect-order-independent">
   <title>&SCons; Builders Are Order-Independent</title>

     <para>

     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; Builder functions are called in
     the &SConstruct; file
     does <emphasis>not</emphasis>
     affect the order in which &SCons;
     actually builds the programs and object files
     you want it to build.
     <footnote><para>In programming parlance,
     the &SConstruct; file is
     <emphasis>declarative</emphasis>,
     meaning you tell &SCons; what you want done
     and let it figure out the order in which to do it,
     rather than strictly <emphasis>imperative</emphasis>,
     where you specify explicitly the order in
     which to do things.
     </para>
     </footnote>.
     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 that moment.
     Instead, you're telling &SCons; what you want accomplished,
     and it's up to &SCons; to figure out how to do that, and to
     take those steps if/when it's necessary.
     you'll learn more about how
     &SCons; decides when building or rebuilding a target
     is necessary in <xref linkend="chap-depends"></xref>, below.

     </para>

     <para>

     &SCons; reflects this distinction between
     <emphasis>calling a builder method like</emphasis> &b-Program;
     and <emphasis>actually building the program</emphasis>
     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.

     </para>

     <para>

     Let's clarify this with an example.
     &Python; has a <function>print</function> function that
     prints a string of characters to the screen.
     If you put <function>print</function> calls around
     the calls to the &b-Program; builder method:

     </para>

     <scons_example name="simple_declarative">
       <file name="SConstruct" printme="1">
print("Calling Program('hello.c')")
Program('hello.c')
print("Calling Program('goodbye.c')")
Program('goodbye.c')
print("Finished calling Program()")
       </file>
       <file name="hello.c">
int main() { printf("Hello, world!\n"); }
       </file>
       <file name="goodbye.c">
int main() { printf("Goodbye, world!\n"); }
       </file>
     </scons_example>

     <para>

     Then when you execute &SCons;,
     you will see the output from calling the <function>print</function>
     function in between the messages about
     reading the &SConscript; files,
     indicating that is when the
     &Python; statements are being executed:

     </para>

     <scons_output example="simple_declarative" os="posix" suffix="1">
       <scons_output_command>scons</scons_output_command>
     </scons_output>

     <para>

     Notice that &SCons; built the &goodbye; program first,
     even though the "reading &SConscript;" output
     shows that <function>Program('hello.c')</function> was called
     first in the &SConstruct; file.

     </para>

   </section>

 </section>

 <section id="sect_building_simple">
 <title>Making the &SCons; Output Less Verbose</title>

   <para>

   You've already seen how &SCons; prints
   some messages about what it's doing,
   surrounding the actual commands used to build the software:

   </para>

   <scons_output example="simple_ex1" os="win32" suffix="3">
      <scons_output_command>scons</scons_output_command>
   </scons_output>

   <para>

   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.

   </para>

   <para>

   One drawback, of course, is that these messages clutter the output.
   Fortunately, they're easily disabled by using
   the &Q; option when invoking &SCons;:

   </para>

   <scons_output example="simple_ex1" os="win32" suffix="4">
      <scons_output_command>scons -Q</scons_output_command>
   </scons_output>

   <para>

   So this User's Guide can focus
   on what &SCons; is actually doing,
   the &Q; option will be used
   to remove these messages from the
   output of all the remaining examples in this Guide.

   </para>

 </section>

</chapter>