.. _Build_System:

============
Build system
============

::

    #load "build/build.bl"

Compiler integrated build pipeline. Build pipline can be used to manage whole project compilation 
process directly in BL. All you need is to create the build file called `build.bl` and specify the
`build_entry` function inside. When `-b` flag is used without need of specifying any files, the
compiler will lookup `build.bl` file in the current directory and execute it in compile time. All 
compilation steps, target input and output can be specified here. Example: :ref:`Build_System_Example`.

Example of minimal build.bl:

.. code-block:: bl

   build :: fn () #build_entry {
       // create new executable target
       exe :: add_executable("MyProgram");

       // add 'main.bl' file into the target 'exe'
       add_unit(exe, "main.bl");

       // Start compilation
       compile(exe);
   }

Start build pipeline using our build.bl file:

.. code-block:: bash

   $ blc -build

Compiler will automatically use build.bl file as build script and execute build function in compile time.
SDK file build/build.bl containing compiler API for build pipeline manipulation is loaded implicitly.

.. warning:: Build API is available only in compile-time.

Basics
======

Create new executable target
----------------------------

Target is a single build target defined as consisting of build Units representing source files
needed for compilation. It’s basically a target compiled into an executable or binary file. Use
:ref:`add_executable` function to specify your target. There are several options related to target,
described later  in this documentation.

.. code-block:: bl

    exe :: add_executable("MyProgram");

Add file into target
--------------------

Use :ref:`add_unit` function to add source files into the target. There is no need to add all files
you want to use, general `load` and `import` will do so automatically. Only `main` or entry files must
be included.

.. code-block:: bl

    add_unit(exe, "main.bl");

Specify output directory
------------------------

Output directory is a directory where all compiler-produced files will be written (i.e. native executables).
Use :ref:`set_output_dir` function to specify this directory, current directory is used by default.

.. code-block:: bl

    set_output_dir(exe, "bin");

Command line argumets
---------------------
All argumets passed after `--build|-b` compiler flag are automatically forwarded into
`command_line_arguments` global variable.

.. toctree::
    :glob:
    :titlesonly:

    build/*