IBM Streams 4.2

sc

The sc command compiles SPL applications.

Usage


sc

>>-+----------------------------------+------------------------->
   '-+- -a--------------------------+-'   
     '- --optimized-code-generation-'     

>--+------------------------+--+---------------------------+---->
   '- --avoid-runtime-yield-'  '-+- -C-------------------+-'   
                                 '- --clean-and-suppress-'     

>--+------------------------+--+-------------------------+------>
   '-compile-time-arguments-'  '- --c++std--=--+-c++98-+-'   
                                               '-c++11-'     

>--+-----------------------------------+------------------------>
   '-+- -d------------------+--=--size-'   
     '- --default-pool-size-'              

>--+----------------------------+------------------------------->
   '- --data-directory--=--path-'   

>--+----------------------------------+------------------------->
   '- --default-relocatable--=--value-'   

>--+----------------------------------+------------------------->
   '- --default-restartable--=--value-'   

>--+-----------------------------------+--+--------------+------>
   '-+- -F--------------+--=--protocol-'  '-+- -g------+-'   
     '- --use-transport-'                   '- --debug-'     

>--+-------------+---------------------------------------------->
   '-+- -h-----+-'   
     '- --help-'     

>--+-------------------------------------------+---------------->
   '-+- -j-----------------+--=--thread_number-'   
     '- --num-make-threads-'                       

>--+-----------------------------------------------+------------>
   '-+- -J---------------------------------------+-'   
     '- --suppress-all-but-the-application-model-'     

>--+-----------------------------+------------------------------>
   '-+- -k---------------------+-'   
     '- --prefer-facade-tuples-'     

>--+----------------------------+------------------------------->
   '-+- -m--------------------+-'   
     '- --makefile-generation-'     

>--+- -M---------------+--=--name------------------------------->
   '- --main-composite-'            

>--+--------------------------------+--------------------------->
   '- --no-mixed-mode-preprocessing-'   

>--+---------------------------------+-------------------------->
   '- --no-optimized-code-generation-'   

>--+------------------------+----------------------------------->
   '- --no-toolkit-indexing-'   

>--+------------------------------+----------------------------->
   '- --output-directory--=--path-'   

>--+----------------------------------------------+------------->
   '- --output-side-effects-behavior--=--behavior-'   

>--+------------------------------------------------+----------->
   '-+- -r------------------------+--=--host_number-'   
     '- --num-distcc-remote-hosts-'                     

>--+---------------------+-------------------------------------->
   '- --rebuild-toolkits-'   

>--+------------------------------------+----------------------->
   '- --state-variable-scoping-behavior-'   

>--+--------------------------+--------------------------------->
   '-+- -t---------+--=--path-'   
     '- --spl-path-'              

>--+--------------------------------+--------------------------->
   '- --transport-stat-dir--=--path-'   

>--+---------------------+--+-------------------+--------------->
   '-+- -v-------------+-'  '- --validate-hosts-'   
     '- --verbose-mode-'                            

>--+---------------------------+--+------------------------+---->
   '-+- -w---------+--=--flags-'  '- --window-clause-order-'   
     '- --ld-flags-'                                           

>--+----------------------------+------------------------------->
   '-+- -x----------+--=--flags-'   
     '- --cxx-flags-'               

>--+----------------------------+--| Deprecated options |------><
   '-+- -z--------------------+-'                           
     '- --code-beautification-'                             

Deprecated options

|--+-------------------------------------+---------------------->
   '- --allow-convenience-fusion-options-'   

>--+--------------------------------------+--------------------->
   '-+- -K---------------------+--=--path-'   
     '- --checkpoint-directory-'              

>--+-------------------------------------------------------+---->
   '-+- -O-----------------------------------------------+-'   
     '- --set-relax-fusion-relocatability-restartability-'     

>--+---------------------------+-------------------------------->
   '-+- -p----------+--=--mode-'   
     '- --part-mode-'              

>--+-------------------------------------------------+---------->
   '-+- -P----------------------+--=--profile_number-'   
     '- --profile-all-operators-'                        

>--+--------------------+--------------------------------------->
   '-+- -s------------+-'   
     '- --static-link-'     

>--+-----------------------------------------+------------------>
   '-+- -S------------------------+--=--rate-'   
     '- --profiling-sampling-rate-'              

>--+-------------------------------+---------------------------->
   '-+- -T-----------------------+-'   
     '- --standalone-application-'     

>--+-----------------------------------------+------------------|
   '-+- -Z--------------------+--=--fraction-'   
     '- --max-pe-cpu-fraction-'

Authority

You do not need any authority to run this command.

Description

sc is the Stream Processing Language (SPL) compiler for IBM® Streams. It is used to compile SPL applications. A successful compilation results in the generation of an application bundle file, which can be submitted to the IBM Streams instance with the streamtool utility.

Options and arguments

-a, --optimized-code-generation

Specifies to generate optimized code with less runtime error checking. The resulting C++ code is compiled at the highest optimization level. Starting with IBM Streams Version 4.2, the SPL compiler generates optimized code by default, but you can still use this option.

With code optimization, the compilation flags used for C++ are -O3 and -NDEBUG for gcc, and SPL assertions and other runtime checks are disabled.

To disable code optimization, use the --no-optimized-code-generation option instead. The --optimized-code-generation (or -a) and --no-optimized-code-generation options are mutually exclusive.

--allow-convenience-fusion-options

This option is deprecated and has no effect.

--avoid-runtime-yield=value

Specifies the behavior to use when the run time encounters a full queue in a ThreadedPort and must wait to add a tuple to the queue of the ThreadedPort. The current behavior is to busy wait, including calls to the pthread_yield subroutine. A performance problem exists when the pthread_yield subroutine is used on RHEL6. This option instructs the run time to use an alternative mechanism when it is waiting on a full queue. The following values are valid:

auto (default): The sc compiler prevents the call to the pthread_yield() subroutine on RHEL6, and forces the call to pthread_yield() on RHEL5.
yes: The sc compiler prevents the call to the pthread_yield() subroutine.
no: The sc compiler forces the call to the pthread_yield() subroutine.

-c, --clean

Specifies to clean the compiler-generated artifacts before compilation.

-C, --clean-and-suppress

Specifies to clean the compiler-generated artifacts and suppress the compilation.

compile-time-arguments

Pass named arguments each in the format name=value to the compiler. The name cannot contain the character = but otherwise is a free form string. It matches the name parameter that is specified in calls that are made to the compile-time argument access functions from within SPL code. The value can be any string, for example:

sc -M my::App hello=a,b,c foo=bar

For more information, see Compile-time values.

--c++std=c++-support

Specifies the C++ standard supported. When you compile an SPL application with --c++std, all C++ artifacts (all operators and native functions) are compiled under that standard. The SPL compiler detects whether the C++ standard is supported by the underlying C++ compiler. The following values are valid for c++-support:

c++98: The default value is c++98. The SPL compiler passes -std=gnu++98 to the g++ compiler.
c++11: The SPL compiler passes -std=gnu++11 to the g++ compiler.

-d, --default-pool-size=size

Specifies the number of hosts in the default host pool. The value must be nonzero (greater than 0). By default, the default pool is unsized.

--data-directory=path

Specifies the location of the data directory. The path can be relative or absolute.

--default-relocatable=value

Specifies whether operators are relocatable by default. Relocatable operators can be relocated to different resources. If you specify --default-relocatable=true, it implies that --default-restartable=true. For more information, see relocatable.

--default-restartable=value

Specifies whether operators are restartable by default. Restartable operators can be restarted. If you specify --default-relocatable=false, it implies that --default-relocatable=false. For more information, see restartable.

-F, --use-transport=protocol

Specifies the default transport protocol. The protocol can be any one of the following values: tcp; llm_rum_tcp; llm_rum_ib. These values are not case-sensitive. The default value is tcp.

Restriction: The LLM transport is not supported on IBM Power Systems™ that are running little endian.

-g, --debug

Specifies to turn on the stream debugger by adding wrapper: sdb as a config for the main composite. A wrapper config specified in the source file, if any, takes precedence.

-h, --help

Specifies to show the command syntax.

-j, --num-make-threads=thread_number

Specifies the number of threads for building the binaries. This option is used as the -j parameter for the make command during the building of the generated C++ code.

-J, --suppress-all-but-the-application-model

Specifies to create an XML-based model of the application (.adl file), but to suppress the creation of other application artifacts as well as the build process.

-k, --prefer-facade-tuples

Specifies to generate facade tuples when possible.

-K, --checkpoint-directory=path

This option is deprecated and has no effect.

-m, --makefile-generation

Specifies to generate a default makefile for building the SPL application.

-M, --main-composite=name

Specifies the main composite to use as the root of the expansion. This value must be a fully qualified name.

--no-mixed-mode-preprocessing

Specifies that the command must not preprocess mixed-mode (.splmm) files.

--no-optimized-code-generation

Specifies that the command must not generate optimized code. The generated C++ code is compiled with -ggdb for gcc.

--no-toolkit-indexing

Specifies that the command must not perform toolkit indexing in the compilation directory.

-O, --set-relax-fusion-relocatability-restartability

This option is deprecated and has no effect.

--output-directory=path

Specifies the directory where the application artifacts are placed.

--output-side-effects-behavior=behavior

Specifies whether to output a message if there are side effects in the output clause. The following options are valid:

ignore: The sc compiler suppresses a warning message.
warn: The sc compiler gives a warning message. This is the default value.
error: The sc compiler gives an error message.

If the –output-side-effects-behavior option is not specified, the sc compiler gives a warning message if there are side effects in the output clause. For information on side effect detection in SPL output clauses, see Side-effects. This option is available in IBM Streams Version 3.0 and later.

-p, --part-mode=mode

This option is deprecated and has no effect.

-P, --profile-all-operators=profile_number

This option is deprecated and has no effect.

-r, --num-distcc-remote-hosts=host_number

Specifies the number of remote hosts to use for distributed compile when you use distcc. The hosts are selected by using the streams_get_available_hosts -query '$build' command. The local host is always part of the compilation.

--rebuild-toolkits

Specifies to run the spl-make-toolkit command, which rebuilds a toolkit if the toolkit is out of date.

The spl-make-toolkit command creates a toolkit.xml file, therefore the directory must be writable by your ID.

-s, --static-link

This option is deprecated and has no effect.

-S, --profiling-sampling-rate=rate

This option is deprecated and has no effect.

--state-variable-scoping-behavior

Specifies that state variables can shadow attributes with the same name.

-t, --spl-path=path

Specifies the toolkit lookup paths. Separate multiple paths with ':'. Each path is a toolkit directory, a directory of toolkit directories, or a toolkit list XML file. This option overrides STREAMS_SPLPATH environment variable.

-T, --standalone-application

This option is deprecated and has no effect.

--transport-stat-dir=path

Specifies the location of the directory to be used for finding transport statistic files.

-v, --verbose-mode

Specifies to provide more detailed compile-time information.

--validate-hosts

Specifies to verify that host names in the placement configs are valid at compile time. The default behavior is to perform the verification when the streamtool submitjob command runs.

-w, --ld-flags=flags

Specifies to pass the flags to ld while linking. For details about the flags, see the GNU linker (ld) documentation.

--window-clause-order

Specifies whether to enforce a specific order for the elements in the window clause. The following options are valid:

any: The sc compiler does not enforce any particular window clause order.

strict: The sc compiler gives an error message if the window clause order does not conform to the following syntax.

opInvokeWindow ::= ID ':' ( 'tumbling' ',' evictionSpec
                          | 'sliding' ',' evictionSpec ( ',' triggerSpec )^? )
                          ( ',' 'partitioned' (',' partitionEvictionSpec)^? )^? ';'

If the --window-clause-order option is not specified, the sc compiler gives a warning message if the elements do not adhere to the window clause syntax.

-x, --cxx-flags=flags

Specifies to pass the flags to the C++ compiler while building. For details about the flags, see the GNU g++ compiler documentation.

-z, --code-beautification

Specifies to generate nicely formatted C++ code. The uncrustify tool needs to be available in the system for this feature to work.

-Z, --max-pe-cpu-fraction=fraction

This option is deprecated and has no effect.

Examples

Assume the following directory layout:

\_ sample/
      \_ WordCount.spl

Further assume that there is a main composite named sample::WordCount defined in the SPL program.

Generate a make file: sc -m -M sample::WordCount. This results in the following directory layout:
```
\_ Makefile
   sample/
     \_ WordCount.spl
```
The generated makefile can be used to compile the application by typing make.
Compile the application: sc -M sample::WordCount. This results in the following directory layout:
```
\_ data/
   output/
     \_ bin/
          \_ standalone
             ...
     \_ sample.WordCount.sab
        ...
   sample/
     \_ WordCount.spl
   toolkit.xml
```
The generated .sab file can be used to submit the application to the IBM Streams instance.
The generated stand-alone executable can be run by using the following command: ./output/bin/standalone.

Use of the C++11 option when compiling your toolkit

When you implement primitive operators and native functions in C++11, document this fact for the users of your toolkit. Toolkit users need to inform the SPL compiler that their application requires compiling under C++11.

In the C++ code, you can check the code is being compiled under C++11 by using the __cplusplus macro.

    #if __cplusplus < 201103L
    #error "This toolkit requires C++11, but is not currently being compiled 
    as C++11."
    #endif

You can also use the opposite comparison to determine whether C++11 is used. This code can be used to take advantage of C++11 features when present, but still work if not.

    #if __cplusplus >= 201103L
    // C++11 specific code
    #else
    // pre-C++11 code
    #endif