aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 4d7cf0fb4a48a6ef20032da44f248a33e73ac381 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
# TODO
Make shell scripts portable. Currently they only work with bash... Use shellcheck to find the issues.

# Simple Build System for Native Languages
Sibs is still in very early testing phase, use with caution. New releases can have changes that are not backwards compatible.

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/<platform>/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(1)|MacOS      |OpenBSD    |Haiku|...        |
|-----|-------|-----------|-----------|-----|-----------|
|✓    |✓      |✓          |✓          |✓    |TBD(2)       |

(1). Msvc, mingw-w64 and cygwin are supported. Cygwin is defined as a linux platform while mingw-w64 is defined as a windows system.
(2). 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 MacOS, OpenBSD and Haiku you need to install from source by running install.sh under cmake directory.
On Linux you can install from source by running install.sh under cmake directory or if you are using Arch Linux you can use the PKGBUILD under distribute/arch_linux. You can also use prebuild package under distribute/linux_x86_64 if you are running on x86_64 machine.
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/<platform>/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 and ldd 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 c/c++ libraries and precompiled shared libraries on Linux usually depend on gcc runtime libraries which are very large, the distributable package becomes very large; a hello world application extracted from its archive is 6 megabytes...
If you want to reduce the size of your package then you will have to compile your project and each dependency from source with clang/musl (gcc c++ runtime is 14mb while clang c++ runtime is 800kb!).

The package command also comes with --bundle-install option which reduces the size of the distributable package by removing libraries in the package that can be downloaded online, and instead the user will download missing libraries when launching the application for the first time (the libraries are cached). This option is good because if the user already has the libraries installed on their system with a package managed then the user dont have to download the libraries and if the user has other software that was distributed using sibs, then their libraries will be shared with your projects; meaning if one project has a library of one version then it's shared with all software that uses same version of the library.

Users are required to manually install some libraries as they can't be included in a distributed package (install with their package manager). These libraries are commonly gpu driver libraries, which vary even if you have the same cpu architecture.
This requirement might be removed later, if the gpu driver libraries required can somehow be detected and downloaded cross platform.
Libraries that are downloaded are available at: https://github.com/DEC05EBA/libraries
# Cross compilation
Automatic cross compilation (`sibs build --platform <platform>`)currently only works from linux_x86_64 to win64 by using mingw-w64. You need to install `mingw-w64-gcc` and optionally `mingw-w64-pkg-config` if you want to use mingw-w64 system installed packages.
Cross compilation does currently not work if you have zig files as zig doesn't support libc when cross compiling at the moment.
You can run `scripts/mingw_package.py` to automatically copy dynamic library dependencies of your executable to the same directory as the executable, so the library can be found when running the executable on windows; this also allows you to bundle your application and distribute it without external dependencies. To run `scripts/mingw_package.py` you need to install pefile python library `sudo pip install pefile`.

Manual cross compilation can be done by replacing c, c++ compilers and linker (ar) using the environment variable CC, CXX and AR.
# 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 or cquery.
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. I recommend using Visual Studio Code along with cquery (https://github.com/cquery-project/cquery/wiki), which gives you very good IDE support for your C/C++ projects:
![Image of cquery extension in Visual Studio Code](preview.png)
If you are using Visual Studio Code then you should add .vscode/ to .gitignore or Visual Studio Code will lag a lot (because cquery adds a lot of files in .vscode 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 = ["any"]
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. Version format is based on [semver 2.0.0](https://semver.org/spec/v2.0.0.html)
### platforms
Required. A list of platforms the package supports. Run `sibs platforms` to view a list of supported platforms.
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.
The value should be a version string, which specified the range of versions that you want to accept as a dependency to only allow dependency version that has the features you need and the version which hasn't changed its interface.
These are examples of the version string format:
```
# Version 1.0.0 or above and less than 2.0.0, same as >=1.0.0 and <2.0.0
1.0.0
# Version 1.0.0 or above
>=1.0.0
# Version above 1.0.0
>1.0.0
# Version exactly 1.0.0
=1.0.0
# Version less than 1.0.0
<1.0.0
# Version 1.0 or above but less than 2.0
1.0 and <2.0
# Version above 1.0 but less or equal to 1.3.2
>1 and <=1.3.2
```
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]