lunaix-os/scripts/build-tools/README.lbuild.md

   1 # LunaBuild
   2
   3 LunaBuild is programmable source file selection tool. It does not build things
   4 by itself, rather, it selects which source file should be feed as input to
   5 other tranditional build tools such as make. The selection logic is completely
   6 programmable and convey through `LBuild` using python syntax.
   7 Since the primary design goal for LunaBuild is simple, lightweight and
   8 standalone. It introduce minimal customisations on the python syntax for better
   9 readbility and it is essentially modified python.
  10
  11 ## Functionalities
  12
  13 ### Native Python Environment
  14
  15 LunaBuild is a superset of python, meaning that all existing functionalities of
  16 python language is still intacted and supported.
  17
  18 This will gives you maximum flexibility on defining your build logic.
  19
  20 ### Import other `LBuild`
  21
  22 Multiple `LBuild`s may be defined across different sub-directory in large scale
  23 project for better maintainability
  24
  25 LunaBuild allow you to import content of other LBuild using python's relative import
  26 feature:
  27
  28 ```py
  29 from . import subdirectory
  30 ```
  31
  32 This import mechanism works like `#include` directive in C preprocessor,
  33 the `from . import` construct will automatically intercepted by the LBuild interpreter and
  34 be replaced with the content from `./subdirectory/LBuild`
  35
  36 You can also address file in the deeper hierarchy of the directory tree, for example
  37
  38 ```py
  39 from .sub1.sub2 import sub3
  40 ```
  41
  42 This will be translated into `./sub1/sub2/sub3/LBuild`
  43
  44 It can also be used in any valid python conditional branches to support
  45 conditional import
  46
  47 ```py
  48 if feature1_enabled:
  49     from . import feature1
  50 elif feature3_enabled
  51     from . import feature3
  52 ```
  53
  54
  55 ### Scoped Data Banks
  56
  57 Almost every build systems is evolved around the list data structure, as its
  58 main task is to collect all interested source files, headers or other build
  59 process relative information. This is also true for LunaBuild.
  60
  61 To better represent this in a more readable way, LunaBuild introduce the concept
  62 of scoped data banks, represented as a automatic global object in the script.
  63
  64 Take a look in the example:
  65
  66 ```py
  67 src.c += "source1.c", "source2.c"
  68 ```
  69
  70 This will append `"source1.c"` and `"source2.c"` into the list named `c` under
  71 the scope of `src`. Which can be clearly interpreted as "collection of c source files"
  72
  73 It is also important to notice that not all databanks are in the forms of list.
  74 Some data banks served special purpose, as we will see below.
  75
  76 LunaBuild defines the following databanks and scope:
  77
  78 + `src` (source files):
  79     + `c` (c files, type: `[]`)
  80     + `h` (headers or include directories, type: `[]`)
  81 + `flag` (source files):
  82     + `cc` (compiler flags, type: `[]`)
  83     + `ld` (linker flags, type: `[]`)
  84 + `config` (configuration options from `LConfig`)
  85     + `CONFIG_<OptionName>` (any valid config name, type: `Any`)
  86 + `env` (environmental variables)
  87     + `<Name>` (any valid env variable name, type: `Any`)