====== Building the StdLib ======

First of all you want to make sure you meet the [[download:building:stdlib-build-requirements|stdlib-build-requirements]].

Then you should clone the GitHub repo, e.g. by
<code>
git clone https://github.com/SacBase/Stdlib.git
</code>
which will create a subdirectory named Stdlib which contains all the Stdlib sources. Before you start building them 
you need to make sure that 

  * you do have a directory named ''.sac2crc'' in your home directory for which you have write permissions.
  *  you have ''sac2c'' within your path. This should be a symlink to the ''RELEASE'' version (''sac2c_p''), not the ''DEBUG'' version (''sac2c_d''), as compilation times would be excessive :-)

Once that is done, you can simply follow the instructions from the README file contained in your copy from GitHub:
{{url>https://raw.githack.com/SacBase/Stdlib/master/README.md}}


===== Current Release =====

<callout type="warning" icon="true">
=== Please be Aware ===
All development of the ''stdlib'' is happening on [[https://github.com/sacbase/stdlib|GitHub]] as of this moment. Furthermore, a new build system has been implemented using CMake. Users still using a other version of stdlib (specifically contained within the Git repository branch ''stdlib-follow'') should skip this section and go to [[#previous_releases|Previous Releases]].
</callout>

Work in progress --- //[[hv15@hw.ac.uk|Hans-Nikolai Viessmann]] 2016/12/05 22:44//

===== Previous Releases =====

==== September 2016 ====

<callout type="info" icon="true">
=== Notice ===
This section concerns itself primarily with the building of the ''stdlib'' from the Git repository branch ''stdlib-follow''.
</callout>

<callout type="info">
=== Package Dependencies ===
You will need ''autoconf'' and related tools to be installed in order to build the ''stdlib''; OSX / macOS users can find this in ''mac-ports''.
</callout>

Change your actual path to your check-out of stdlib. Then do
<code>
./bootstrap                           # this will scan through all source files
                                      # under /src and store their location for
                                      # later dependency generation. We also
                                      # call autotools and generate the
                                      # ./configure scripts

./configure                           # generate Makefiles

make SUB_CONFIGURE_FLAGS=--disable-opencv
                                      # builds all modules for all (several?)
                                      # targets within the target/<..target..>
                                      # directory. The make command can
                                      # instruct the per-target configuration
                                      # to enable/disable some features. This
                                      # is done by setting the variable
                                      # SUB_CONFIGURE_FLAGS on the command
                                      # line. See `sub/configure --help` for
                                      # further features that can be
                                      # enabled/disabled.

make EXCLUDEMODS="ArrayIO RGB"        # the EXCLUDEMODS var can be used to
                                      # instruct the build system to NOT
                                      # compile the listed modules, even
                                      # against what has been configured.

make INCLUDEMODS="ArrayBasics"        # the INCLUDEMODS will completely
                                      # override the build system and only
                                      # compile the listed modules, including
                                      # their dependencies recursively.

make COPT=2                           # the COPT allows you to control what
                                      # optimisation level is used by the
                                      # compiler, e.g. COPT=1 equates to -O2

make LINKSETSIZE=25                   # the LINKSETSIZE allows you to control
                                      # the SAC compilers `-linksetsize' flag,
                                      # e.g. LINKSETSIZE=15 equates to
                                      # -linksetsize 15

make install                          # moves all your targets into the 
                                      # location of the sac2c compiler
</code>

Note, that any call to ''sac2c'' will try to find any used or imported modules in the installed version of the stdlib that was installed with ''sac2c'' of the very same revision number! So, if you have a newer version of ''sac2c'', be it installed or not, it will no longer find previously compiled and installed libraries! Likewise, if you modify your stdlib, compile it but do not install it, it will not be picked up!

To tackle these issues, you may want to add your stdlib-build-directory to your search pathes in ''TREE_OUTPUTDIR'' and ''LIB_OUTPUTDIR''. For convenience, we recommend that you create or add to your local sac2crc file ''˜/.sac2crc'' the following lines and replace ''STDLIB-BUILD_DIR'' by the absolute path to your own stdlib build:

<code>
target add_stdlib_local:
TREE_OUTPUTDIR += ":STDLIB-BUILD_DIR/lib"
LIB_OUTPUTDIR  += ":STDLIB-BUILD_DIR/lib"

target default_sbi :: add_default_sbi :: add_local :: add_stdlib_local:
</code>

<callout type="info" icon="true">
==== Suggestion for Newbie Developers ====

If your aim is to **primarily** do **stdlib development** with no or almost no compiler development, we suggest
you do **not install** a stdlib at all!

If you are doing **primarily** **sac2c development** we suggest you install a compiled version for each version
of ''sac2c'' that you install. That way, you can try older compiler versions without being required to recompile the
corresponding stdlib!

In **both cases** you **should** put the above lines into your local ''.sac2crc'' file!
</callout>

===== Pitfalls =====

  * Please note, that the set up suggested above puts your local built directory at the end of the search path. This may lead to a surprise in the following scenario: You build sac2c, you install it and then you never change your compiler. If you now modify the stdlib without installing it, the new version of your stdlib will not be picked up. To avoid this we recommend you either install after each modification of the stdlib -or- you never install the stdlib and always use the above addition to your sac2crc file! 
  * Note also, that the local (non-installed) version of the stdlib does **not** encode the compiler version. That, at least in principle, allows any version of ''sac2c'' to use the locally compiled stdlib. All that is required is to shadow the installed stdlib by using '':='' instead ''+='' in your local ''.sac2crc''. However, this may entail encountering a sac2c error message similar to <code make>abort: The module 'Array' (/Volumes/Users/sbs/stdlib/lib/tree/host/libArrayTree.dylib) uses an incompatible syntax tree layout. Please update the module and compiler to the most recent version.
Compilation failed while Loading SAC program, 1 warning(s).</code> As a positive side effect, the suggested setup in ''./sac2crc'' allows you to keep the rebuilds of the local stdlib to a minimum during compiler development. Despite changes in the compiler version (with and without commits), the stdlib only requires rebuilding when the syntax tree layout is being modified :-)