Add documentation for configuration options (#2977)

JerryScript-DCO-1.0-Signed-off-by: Dániel Bátyai dbatyai@inf.u-szeged.hu
2019-07-23 15:32:41 +02:00
parent 4a9e185840
commit 5d6eebac4c
3 changed files with 256 additions and 2 deletions
@@ -0,0 +1,192 @@
+## Setting up prerequisites
+
+Currently, only Ubuntu 14.04+ is officially supported as primary development environment.
+
+There are several dependencies, that should be installed manually. The following list is the absolute minimum for building:
+
+- `gcc` or any C99-compliant compiler (native or cross, e.g., arm-none-eabi)
+- `cmake` >= `2.8.12.2`
+
+Several scripts and tools help the building and development process, thus it is recommended to have the following installed as well:
+
+- `bash` >= `4.3.11`
+- `cppcheck` >= `1.61`
+- `vera++` >= `1.2.1`
+- `python` >= `2.7.6`
+
+```bash
+sudo apt-get install gcc gcc-arm-none-eabi cmake cppcheck vera++ python
+```
+
+To make our scripts run correctly, several shell utilities should be available on the system:
+
+- `awk`
+- `bc`
+- `find`
+- `sed`
+
+## Building JerryScript
+
+**To build debug version for Linux**
+
+```bash
+python tools/build.py --debug
+```
+
+**To build debug version for Linux without LTO (Link Time Optimization)**
+
+```bash
+python tools/build.py --debug --lto=off
+```
+
+**To enable more verbose outputs for debugging**
+
+```bash
+tools/build.py --debug --logging=on --error-messages=on --line-info=on
+```
+
+**Add custom arguments to CMake**
+
+```bash
+python tools/build.py --cmake-param=CMAKE_PARAM
+```
+
+**Set a profile mode (ES5.1, subset of ES2015, minimal)**
+
+```bash
+python tools/build.py --profile=es5.1|es2015-subset|minimal
+```
+
+See also the related [README.md](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md).
+
+**Use (compiler-default, external) libc**
+
+The default libc is the compiler-default libc but you can use an external libc as well:
+
+- compiler-default libc:
+
+```bash
+python tools/build.py
+```
+
+- external libc:
+
+```bash
+python tools/build.py --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="ext-c"
+```
+
+**Add toolchain file**
+
+The ```cmake``` dir already contains some usable toolchain files, which you can use in the following format:
+
+```bash
+python tools/build.py --toolchain=TOOLCHAIN
+```
+
+For example the cross-compile to RaspberryPi 2 is something like this:
+
+```bash
+python tools/build.py --toolchain=cmake/toolchain_linux_armv7l.cmake
+```
+
+**Use system memory allocator**
+
+```bash
+python tools/build.py --system-allocator=on
+```
+
+*Note*: System allocator is only supported on 32 bit systems.
+
+**Enable 32bit compressed pointers**
+
+```bash
+python tools/build.py --cpointer-32bit=on
+```
+
+*Note*: There is no compression/decompression on 32 bit systems, if enabled.
+
+**Change default heap size (512K)**
+
+```bash
+python tools/build.py --mem-heap=256
+```
+
+If you would like to use more than 512K, then you must enable the 32 bit compressed pointers.
+
+```bash
+python tools/build.py --cpointer-32bit=on --mem-heap=1024
+```
+
+*Note*: The heap size will be allocated statically at compile time, when JerryScript memory
+allocator is used.
+
+**To build with libfuzzer support**
+
+```bash
+CC=clang python tools/build.py --libfuzzer=on --compile-flag=-fsanitize=address --lto=off
+```
+
+Check the documentation of libfuzzer to get the runtime settings of the created fuzzer
+binary: https://llvm.org/docs/LibFuzzer.html.
+
+**To get a list of all the available buildoptions for Linux**
+
+```bash
+python tools/build.py --help
+```
+
+## Checking patch
+
+```bash
+python tools/run-tests.py --precommit
+```
+
+### Running only one type of test
+
+**To run build option tests**
+
+```bash
+python tools/run-tests.py --buildoption-test
+```
+
+**To run unittests**
+
+```bash
+python tools/run-tests.py --unittests
+```
+
+**To run jerry-tests**
+
+```bash
+python tools/run-tests.py --jerry-tests
+```
+
+**To run jerry-test-suite**
+
+```bash
+python tools/run-tests.py --jerry-test-suite
+```
+
+**To run signed-off check**
+
+```bash
+python tools/run-tests.py --check-signed-off
+```
+
+**To run cppcheck**
+
+```bash
+python tools/run-tests.py --check-cppcheck
+```
+
+**To run vera check**
+
+```bash
+python tools/run-tests.py --check-vera
+```
+
+**To get a list of all the available test options**
+
+```bash
+python tools/run-tests.py --help
+```