<?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;
]>

<section id="sect-variant-examples"
         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>Variant Build Examples</title>

  <para>

  The &variant_dir; keyword argument of
  the &SConscript; function provides everything
  we need to show how easy it is to create
  variant builds using &SCons;.
  Suppose, for example, that we want to
  build a program for both Windows and Linux platforms,
  but that we want to build it in directory on a network share
  with separate side-by-side build directories
  for the Windows and Linux versions of the program.
  We have to do a little bit of work to construct paths,
  to make sure unwanted location dependencies don't creep in.
  The top-relative path reference can be useful here.
  To avoid writing conditional code based on platform,
  we can build the <parameter>variant_dir</parameter>
  path dynamically:

  </para>

  <scons_example name="variants_ex">
    <file name="SConstruct" printme="1">
platform = ARGUMENTS.get('OS', Platform())

include = "#export/$PLATFORM/include"
lib = "#export/$PLATFORM/lib"
bin = "#export/$PLATFORM/bin"

env = Environment(
    PLATFORM=platform,
    BINDIR=bin,
    INCDIR=include,
    LIBDIR=lib,
    CPPPATH=[include],
    LIBPATH=[lib],
    LIBS='world',
)

Export('env')

env.SConscript('src/SConscript', variant_dir='build/$PLATFORM')
    </file>
    <directory name="src"></directory>
    <directory name="src/hello"></directory>
    <directory name="src/world"></directory>
    <file name="src/SConscript">
Import('env')
SConscript('hello/SConscript')
SConscript('world/SConscript')
    </file>
    <file name="src/hello/SConscript">
Import('env')
hello = env.Program('hello.c')
env.Install('$BINDIR', hello)
    </file>
    <file name="src/hello/hello.c">
#include "world.h"
int main(int argc, char *argv[]) { printf "hello.c\n"; world(); }
    </file>
    <file name="src/world/SConscript">
Import('env')
world = env.Library('world.c')
env.Install('$LIBDIR', world)
env.Install('$INCDIR', 'world.h')
    </file>
    <file name="src/world/world.h">
#define STRING "world.h"
extern int world();
    </file>
    <file name="src/world/world.c">
int world() { printf "world.c\n"; }
    </file>
  </scons_example>

  <para>

  This SConstruct file,
  when run on a Linux system, yields:

  </para>

  <scons_output example="variants_ex" os="posix" suffix="1">
    <scons_output_command>scons -Q OS=linux</scons_output_command>
  </scons_output>

  <para>

  The same SConstruct file on Windows would build:

  </para>

  <scons_output example="variants_ex" os="win32" suffix="2">
    <scons_output_command>scons -Q OS=windows</scons_output_command>
  </scons_output>

  <para>

  In order to build several variants at once when using the
  <parameter>variant_dir</parameter> argument to &SConscript;,
  you can call the function repeatedly - this example
  does so in a loop. Note that the &f-link-SConscript; trick of
  passing a list of script files, or a list of source directories,
  does not work with <parameter>variant_dir</parameter>,
  &SCons; allows only a single &SConscript; to be given if
  <parameter>variant_dir</parameter> is used.

  </para>

  <scons_example name="variants_ex2">
    <file name="SConstruct" printme="1">
env = Environment(OS=ARGUMENTS.get('OS'))
for os in ['newell', 'post']:
    SConscript('src/SConscript', variant_dir='build/' + os)
    </file>
  </scons_example>

  <!--
  <scons_output example="variants_ex2" suffix="1">
    <scons_output_command>scons -Q</scons_output_command>
  </scons_output>

  -->

</section>
