path: root/README.md

# Simple Build System for Native Languages
Sibs is still in very early testing phase, should only be used if you want to toy around with it. Every new release can have changes that break backwards compatibility since the design has not been decided yet.

Sibs is inspired by [Cargo](https://github.com/rust-lang/cargo/), you can think of it like a C/C++/Zig version of Cargo.
Zig support has not been tested properly yet and currently always links to c library.
You can run zig tests with `sibs test --file filepath` or `sibs test --all-files`.
Currently zig tests are cached because ninja build system is used, which means if source files do not change between runs.
Currently zig files generate header files and include exported functions into sibs-build/generated-headers/zig and the generated headers
are usable from c/c++ by using including: `#include <zig/INSERT_ZIG_HEADER_FILE_NAME_HERE>`.
If your project contains zig files then it will currently only run on Linux, Windows and MacOS as zig doesn't support more platforms at the moment.

The CMakeLists.txt should only be used during development or when installing sibs for the first time.
To compile under windows you can use vcpkg to install dependencies and then generate visual studio project using cmake.

List of packages can be found at https://gitlab.com/DEC05EBA/sibs_packages/raw/master/packages.json

### Supported platforms
|Linux|Windows|MacOS      |OpenBSD    |...        |
|-----|-------|-----------|-----------|-----------|
|✓    |✓      |✓         |✓          |TBD*       |

\* Sibs is intended to work on as many platforms as possible, you can help by porting sibs to another platform. Should only be minor changes if the platform is unix-like.

Linux is the primary platform, the platform which master branch is guaranteed to compile on.

# Installation
Newest version of sibs builds itself. If you don't already have sibs installed and you are using Windows then you can find prebuilt binary under msvc folder.
On Linux, MacOS and OpenBSD you need to build from source by running install.sh under cmake directory.
After you've installed sibs once, you can install new versions by running install.sh (or use `sibs.exe build --release` if you are on windows, and sibs binary will be located under sibs-build/release/sibs.exe).
For easiest usage of sibs under windows, add msvc subdirectory to PATH environment variable. msvc subdirectory also contains additional libraries and software that is needed for sibs to run
with the only missing software being cmake.

Dependencies that are required to build sibs from source are:  
`libcurl, libarchive, libgit2, curl`  
  
`Ninja (build system)` needs to be installed on the system to be able to build projects. CMake can be required for some projects that uses cmake files to build project instead of sibs.
Ccache is currently required on non-windows platforms but it will later be removed and replaced with sibs own caching system. Ninja will also be removed as backend build system.
# Usage
After you have installed sibs, execute `sibs` without any arguments and you will get a list of commands and description for them.
# Package
Sibs supports creating a redistributable packages of projects (currently only on Linux, run `sibs package --bundle`). Packaging is in testing phase and may not work for all projects. Currently you need to have python3, ldd and patchelf installed and also set the environment variable SIBS_SCRIPT_DIR to scripts sub directory which is in sibs root directory (the directory that contains package.py).
Currently a script file is generated which should be used to run the project. The name of the script file is the same as project. This script file will most likely to be removed later. Do NOT run the executable called "program".
Because creating a package is currently done by copying gcc/clang libraries and not musl, the distributable package becomes very large; a hello world application extracted from its archive is 6 megabytes...
# IDE support
Sibs generates a compile_commands.json in the project root directory when executing `sibs build` and tools that support clang completion can be used, such as YouCompleteMe.
There are several editors that support YouCompleteMe, including Vim, Emacs and Visual Studio Code. Visual studio code now also supports clang completion with C/C++ extension by Microsoft; the extension will ask you which compile_commands.json file you want to use and you can choose the compile_commands.json in the project root directory.
# Tests
If your project contains a sub directory called "tests" then that directory will be used a test project. The test directory may contain a project.conf file which can contain \[dependencies] block for specifying test only dependencies. The test automatically includes the parent project as a dependency.
# Project configuration template
```toml
[package]
name = "packageName"
type = "library"
version = "0.1.0"
platforms = ["linux", "linux32", "linux64", "win", "win32", "win64", "macos32", "macos64", "bsd", "openbsd", "openbsd32", "openbsd64"]
authors = ["DEC05EBA <0xdec05eba@gmail.com>"]

[dependencies]
catch2 = "0.1.0"
xxhash = "0.1.0"
cisb = { git = "https://github.com/DEC05EBA/cisb.git", branch = "master", revision = "c0c46a4" }

[lang.c]
version = "c11"

[lang.cpp]
version = "c++14"

[define]
BOOST_ASIO_SEPERATE_COMPILATION = "1"

[define.static]
BOOST_COMPILE_STATIC = "1"

[define.dynamic]
BOOST_COMPILE_DYNAMIC = "1"

[config]
include_dirs = ["include"]
ignore_dirs = ["examples"]
expose_include_dirs = ["include"]

[config.win32.static.debug]
lib = "windows/x86/static/debug"

[config.win32.static.release]
lib = "windows/x86/static/release"

[config.win64.static.debug]
lib = "windows/x64/static/debug"

[cmake]
dir = "."
args = ["ENTITYX_RUN_BENCHMARKS=0"]

[cmake.static]
args = ["ENTITYX_BUILD_SHARED=0"]

[cmake.dynamic]
args = ["ENTITYX_BUILD_SHARED=1"]
```
## package
### name
Required
### type
Required. Should be one of: "executable", "static", "dynamic", "library"
### version
Required. Version string has to be in the format of "xxx.yyy.zzz" where xxx is major, yyy is minor and zzz is patch
### platforms
Required. A list of platforms the package supports. Can contain the following values: "any", "linux", "linux32", "linux64", "win", "win32", "win64", "macos32", "macos64", "bsd", "openbsd", "openbsd32", "openbsd64".
If platforms contains "any" then there is no need to specify other platforms
### authors
Optional. A list of authors
## dependencies
Optional. A list of dependencies which are specified in name-value pairs where the name is the name of the dependency, which should match the dependency name under the packages name specified in its project.conf file.
Currently, the value is the version and has to be an exact match for the package version, which is specified in the dependencies project.conf file.
This will later change and you should be able to choose minimum version and range of versions.
Dependencies are automatically choosen from system (linux, mac) or if no package manager exists, then it's download from an url (see https://gitlab.com/DEC05EBA/sibs_packages).
The dependency can also be a git project, in which case it will have the fields 'git' and optionally 'branch' and 'revision'.
'git' specifies the url to the git repository, 'branch' is the git branch that should be used - defaults to 'master'.
'revision' is the git revision to checkout, defaults to 'HEAD' (latest commit).

Dependencies can also be added to a project but adding sub directories with project.conf file.
The best way to do this is to create another git project for the dependency and then adding that git project as a git submodule.
Using sub projects allows you to modify dependency and propagate changes to dependant project without pushing changes to remote git repository (faster development).
## lang.*
Optional. Allows you to change language specific configuration. \[lang.c] is for C and \[lang.cpp] is for C++.
Version specifies the language version, for \[lang.c] the version can be ansi, c89, c99 or c11 - if not set, c11 will be used.
For \[lang.cpp] the version can be c++11, c++14 or c++17 - if not set, c++14 will be used
## define
Optional. A list of definitions which are specified in name-value pairs where the name is the preprocessor to define (in c: #define name value)
## define.static
Works like \[define], but these definitions are only used when building static project. If a definition with the same exists in \[define], then it's overwritten
## define.dynamic
Works like \[define], but these definitions are only used when building dynamic project. If a definition with the same exists in \[define], then it's overwritten
## config
### include_dirs
Optional. A list of directories which should be specified as global include directories when compiling. This means that instead of using relative paths to header files, you can include the directory with headers and then you only have to specify the header name when using #include
### ignore_dirs
Optional. A list of directories to ignore. This means that if the ignored directory contains source files, then they wont be included in the build
### expose_include_dirs
Optional. A list of directories which contains (header) files which should be exposed to dependencies as directories to include globally. This means that dependencies can include (header) files from the dependency without specifying path to the dependency
## config.*
Optional. The name is structured in the following way: config.platform.libraryType.optimizationLevel
where platform is any of the platforms specified under \[package] (or if package contains "any", then it can be any other platform). LibraryType is either "static" or "dynamic" - different configurations depending on if the package is included as a static or dynamic library by a dependant package. OptimizationLevel is either "debug" or "release", depending on which optimization level the "root" package was built with ("root" package is usually the project which is an executable)
### lib
Optional. A directory which contains .lib or .dll files which should be included in dependant projects that uses this project
## cmake
Optional. Using this allows you to build cmake projects. If a project contains cmake in the project.conf file, then sibs wont build the project itself
and will use cmake instead. Sibs will put the built executable and library files into the same location they would be if sibs build them,
meaning you can have dependency to a cmake project from a sibs project and it will automatically use the dependency library files
### dir
Optional. Directory that contains CMakeLists.txt. If this is not specified, the project root will be used (same location where project.conf is located)
### args
Optional. List of arguments to cmake. The arguments should be in the same format as "-D" arguments (options) in cmake, except they should exclude "-D".
Do not use CMAKE_BUILD_TYPE as sibs will automatically use it depending on the optimization level the user specifies when building project.
## cmake.*
Optional. The name is structured in the following way: config.libraryType 
where libraryType is either "static" or "dynamic" - different configurations depending on if the package is included as a static or dynamic library by a dependant package.
Args specified under \[cmake.static] or \[cmake.dynamic] are appended to the args specified under \[cmake]