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` file which is essentially a python
   7 script. As the primary design goal for LunaBuild is simple, lightweight and
   8 standalone. It just plain python, with some extra predefined functions and
   9 automatic variables, so does not force user to learn some other weird domain
  10 specific language (yes, that's you, CMake!).
  11
  12 ## Usage
  13
  14 Invoke `./luna_build.py <root_lbuild> -o <out_dir>`. It will output two file
  15 to the `<out_dir>`: `sources.list` and `headers.list`. Contains all the source
  16 files and header files to be used by the build process.
  17
  18 ## Core Functions
  19
  20 LunaBuild provide following function to help user select source files.
  21
  22 ### [func] `use(lbuild_path)`
  23
  24 Include another LBuild file. `lbuild_path` is the path relative to current
  25 directory, pointed to the file. It can be also pointed to a directory, for
  26 which the LBuild file is inferred as `$lbuild_path/LBuild`.
  27
  28 For example:
  29
  30 ```py
  31 use("dir")
  32 use("dir/LBuild")
  33 ```
  34
  35 both are equivalent.
  36
  37 ### [func] `sources(src_list)`
  38
  39 Select a list of source files, all paths used are relative to current
  40 directory. For example,
  41
  42 ```py
  43 sources([ "a.c", "b.c", "c.c" ])
  44 ```
  45
  46 ### [func] `headers(src_list)`
  47
  48 Select a list of header file or include directory, all paths used are
  49 relative to current directory. For example,
  50
  51 ```py
  52 headers([ "includes/", "includes/some.h" ])
  53 ```
  54
  55 ### [func] `configured(name)`
  56
  57 Check whether a configuration is present, the name for the configuration
  58 is defined by external configuration provider.
  59
  60 ### [func] `config(name)`
  61
  62 Read the value of a configuration, raise exception is not exists.
  63
  64 ### [var] `_script`
  65
  66 Automatic variable, a path to the current build file.
  67
  68 ## Short-hands
  69
  70 LunaBuild provide some useful short-hand notations
  71
  72 ### Conditional Select
  73
  74 Suppose you have two source files `src_a.c` and `src_b.c`, for which
  75 their selection will be depends on the value of a configuration
  76 `WHICH_SRC`. A common way is to use `if-else` construct
  77
  78 ```py
  79 if config("WHICH_SRC") == "select_a":
  80     sources("src_a.c")
  81 elif config("WHICH_SRC") == "select_b":
  82     sources("src_b.c")
  83 ```
  84
  85 LunaBuild allow you to short hand it as such:
  86
  87 ```py
  88 sources({
  89     config("WHICH_SRC"): {
  90         "select_a": "src_a.c",
  91         "select_b": "src_b.c",
  92         # more...
  93     }
  94 })
  95 ```
  96
  97 It can also be extended easily for multiple choices and allow nesting.
  98
  99 You may also notice we no longer wrap the parameter with square bracket,
 100 this is also another short-hand, the array notation is not needed when
 101 there is only one element to add.