\section senfutil_overview Building Projects using SENF
When building projects using senf, SENFSCons has a very simple helper module \ref senfutil to
- make the building of libraries utilizing senf simpler:
- \code
- import sys
- sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons'))
- import os.path, glob, senfutil
+ make the building of libraries utilizing senf simpler.
- env = Environment()
+ \see \ref senf_senfutil
+*/
- senfutil.SetupForSENF( env )
+/** \page senf_senfutil SENF SCons build utility (senfutil.py)
- env.Append(
+ \autotoc
- LIBS = [ ],
- CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ],
- LINKFLAGS = [ ],
+ The \c senfutil utility for SCons helps setting up a project to compile against SENF:
- CXXFLAGS_debug = [ ],
- LINKFLAGS_debug = [ ],
- LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
+ \li \c senfutil adds all necessary libraries to link against
+ \li \c senfutil will set necessary compile options.
+ \li \c senfutil supports normal, debug and final project build options
+ \li \c senfutil allows specifying variables on the scons command line
+ \li \c senfutil supports more readable compile-time SENF loglevel configuration
- CXXFLAGS_final = [ '-O3' ],
- LINKFLAGS_final = [ ],
- LOGLEVELS_final = [ ],
+ Using the utility is quite simple
- SENF_BUILDOPTS = [ ],
+ \code
+ import sys
+ sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons'))
+ import glob, senfutil
+
+ env = Environment()
+ senfutil.SetupForSENF(env)
+ # senfutil.DefaultOptions(env)
+ # Set or change SCons environment variables with env.Append, env.Replace or env.SetDefault
+ env.Append(
+ CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ],
+ CXXFLAGS_final = [ '-O2' ],
+ CXXFLAGS_normal = [ '-O0', '-g' ],
+ CXXFLAGS_debug = [ '$CXXFLAGS_normal' ],
+
+ LINKFLAGS_normal = [ '-Wl,-S' ],
+
+ LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ],
)
env.Default(
- env.Program( target = 'udpforward',
- source = glob.glob('*.cc') )
+ env.Program( target='udpforward', source=glob.glob('*.cc') )
)
-
- env.Clean(DEFAULT_TARGETS, [ 'udpforward.log', 'udpforward.pid' ])
\endcode
This example builds a simple binary from a number of source files (all '.cc' files). It links
<tt>senfutil.SetupForSENF( env )</tt>.
This script automatically uses a SENF installation either symlinked or imported into the current
- project in directory 'senf' or, if this directory does not exist, a globaly installed SENF. A
- locally installed SENF is automatically recompiled if needed. Parallel building is also
- supported.
+ project in directory 'senf' or, if this directory does not exist, a globally installed SENF.
+
+ \section senf_senfutil_options Build options
+
+ \c senfutil supports the <tt>debug=1</tt> or <tt>final=1</tt> build options. These parameters
+ select one of the build configurations 'debug', 'normal' or 'final'. The following variables are
+ supported each with separate values for all three configurations:
+
+ \li \c CXXFLAGS
+ \li \c CPPDEFINES
+ \li \c LINKFLAGS
+ \li \c LOGLEVELS
+
+ \c senfutil will detect the type of SENF library used (final or not) and set the correct compile
+ options.
+
+ \section senf_senfutil_loglevels Specifying compile-time loglevels
+
+ To simplify specifying the compile-time loglevel configuration, the build variable \c LOGLEVELS
+ (and it's build configuration specific variants) may be set. This variable will be parsed and
+ converted into the correct \c SENF_LOG_CONF definition. The \c LOGLEVELS Syntax is
- This script automatically supports the \c final and \c LOGLEVELS command line parameters. The
- LOGLEVELS parameter uses a much more readable syntax than SENF_LOG_CONF:
+ \par "" \e optional_stream \c | \e optional_area | \e level
+
+ where \e optional_stream and \e optional_area are optional fully scoped C++ names (e.g. \c
+ senf::log::Debug) and \e level is the loglevel. There must be \e no whitespace in a single
+ specification, multiple specifications are either specified using an array or separated with
+ whitespace.
+
+ \section senf_senfutil_default Default options
+
+ In the example above, all compile options are set manually. To specify the default customary
+ compile options for SENF programs, \c senfutil.DefaultOptions(env) is provided. This function is
+ identical to:
+
+ \code
+ senfutil.DefaultOptions(env) =>
+ env.Append(
+ CXXFLAGS = [ '-Wall', '-Woverloaded-virtual' ],
+ CXXFLAGS_final = [ '-O2' ],
+ CXXFLAGS_normal = [ '-O0', '-g' ],
+ CXXFLAGS_debug = [ '$CXXFLAGS_normal' ],
+
+ LINKFLAGS_normal = [ '-Wl,-S' ],
+ )
+ \endcode
+
+ Thus above example can be simplified to
+ \code
+ import sys
+ sys.path.extend(('senf/site_scons','/usr/lib/senf/site_scons'))
+ import glob, senfutil
+
+ env = Environment()
+ senfutil.SetupForSENF(env)
+ senfutil.DefaultOptions(env)
+
+ env.Append( LOGLEVELS_debug = [ 'senf::log::Debug||VERBOSE' ] )
+
+ env.Default(
+ env.Program( target = 'udpforward', source = glob.glob('*.cc') )
+ )
+ \endcode
+
+ \section senf_senfutil_arguments 'scons' Command line arguments
+
+ \c senfutil automatically parses SCons command line arguments into the SCons build
+ environment. This allows specifying any parameter on the command line:
<pre>
- $ scons -j2 final=1 \
- LOGLEVELS='senf::log::Debug||IMPORTANT myapp::Transactions|mytrans::Area|VERBOSE'
+ $ scons CXXCOM=mygcc CXXFLAGS+=-mtune=geode
</pre>
-*/
+ You may either set variables unconditionally using '=' or append values to the end of a list
+ using '+='.
+ */
/** \page senf_usage Using the SENF framework
projects / senf.git / blobdiff