1# Bootstrapping 2 3Currently an officially supported host OS for development, building and testing is Ubuntu 18.04 and Ubuntu 20.04. 4The full list of packages required for building and testing the project is specified in 5`scripts/deps-lists` files. These packages can be installed either manually or by running 6a bootstrap script: 7 8``` 9$ sudo ./scripts/install-deps-ubuntu 10``` 11 12For more bootstrapping options, run: 13 14``` 15$ sudo ./scripts/install-deps-ubuntu --help 16``` 17 18E.g. for development purposes you should run: 19 20``` 21$ sudo ./scripts/install-deps-ubuntu -i=dev 22``` 23 24If you want additionally to install Python dependencies for running tests add a parameter `-i=test`: 25 26``` 27$ sudo ./scripts/install-deps-ubuntu -i=dev -i=test 28``` 29It creates a virtual environment .venv-panda in your home directory with all required dependencies. 30Later, tests Python scripts can activate this environment. If you already have run with the parameter `-i=test` 31the second time it might be skipped. 32 33# Third party 34 35Panda uses third party libraries. To install the libraries and apply patches, run: 36 37``` 38$ ./scripts/install-third-party --force-clone 39``` 40 41# Building 42 43Assuming your system is bootstrapped, please run the following commands in the root of the project: 44 45``` 46$ mkdir panda-build 47$ cd panda-build 48$ cmake /path/to/panda/repository -GNinja 49$ ninja 50``` 51 52This will build Panda in debug mode with your default C++ compiler. All supported compilers can be 53found in `cmake/toolchain`. E.g., to build with Clang 14, pass a path to the corresponding toolchain 54file during configuration: 55 56``` 57$ cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/panda/repository/cmake/toolchain/host_clang_14.cmake /path/to/panda/repository 58``` 59 60## Explicitly setting build types 61 62Recommended way to build Panda is to set `CMAKE_BUILD_TYPE` variable explicitly during configurations. Supported values are: 63 64| Mode | Assertions | Optimizations | Debug info | 65| ---- | ---------- | ------------- | ---------- | 66| `Debug ` | Yes | None (CMake default) | `-g` (CMake default) | 67| `Release` | No | `-O3` (CMake default) | None (CMake default) | 68| `FastVerify` | Yes | `-O2` | `-ggdb3` | 69 70Notes: 71 72* Other common modes (`RelWithDebInfo`, `MinSizeRel`, `DebugDetailed`) should work but they are not tested in CI. 73* Unlike `RelWithDebInfo`, `FastVerify` preserves assertions (and provides more verbose debug information). 74 Use this build type for running heavy test suites when you want both fast-running code and debuggability. 75* `DebugDetailed` gives more debug information than `Debug`, it can be usefull for debugging unit tests for example. 76 77Example: 78 79``` 80$ cmake -DCMAKE_BUILD_TYPE=Release ... 81``` 82 83## Building with LLVM Backend 84 85If you want to build Ark with LLVM Backend you need to build first special modified LLVM 15 binaries. 86 * Clone repository from [gitee.com](https://gitee.com/openharmony/third_party_llvm-project) 87 * Check [README](scripts/llvm/README.md) file about build process 88 * Use build [script](scripts/llvm/build_llvm.sh) 89 90If modified LLVM available in `/opt`, the following two options are necessary 91to build Ark with LLVM Backend functions. 92 93```cmake 94cmake -DPANDA_LLVM_BACKEND=true -DLLVM_TARGET_PATH=/opt/llvm-15-{type}-{arch} ... 95``` 96 97The `PANDA_LLVM_BACKEND` enables: 98 991. LLVM Irtoc Interpreter. Use `-DPANDA_LLVM_INTERPRETER=OFF` to disable. 1002. LLVM Fastpaths compilation. Use `-DPANDA_LLVM_FASTPATH=OFF` to disable. 1013. LLVM Interpreter inlining. Use `-DPANDA_LLVM_INTERPRETER_INLINING=OFF` to disable. 1024. LLVM AOT compiler. Use `-DPANDA_LLVM_AOT=OFF` to disable. 103 104`PANDA_LLVM_INTERPRETER`, `PANDA_LLVM_FASTPATH`, and `PANDA_LLVM_AOT` are `ON` if `PANDA_LLVM_BACKEND` is turned on. 105 106It is recommended to choose `clang` compiler using toolchain files: `-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain/host_clang_14.cmake`. 107By default GNU compiler `c++` is used, but some features are not available in such `gcc` builds. 108 109## Cross ARM64 build with LLVM Backend 110 111For cross-build, when e.g. `-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain/cross-clang-14-qemu-aarch64.cmake` is used, 112two LLVM-paths options are required when all LLVM Backend functions are enabled. 113 * First one is target LLVM, like `-DLLVM_TARGET_PATH=/opt/llvm-15-debug-aarch64` 114 * It is required for AOT, so, alternatively, you can use `-DPANDA_LLVM_AOT=OFF`. 115 * Second one is host LLVM, like `-DLLVM_HOST_PATH=/opt/llvm-15-debug-x86_64` 116 * It is required for Irtoc compilation, so, alternatively, you can disable appropriate Interpreter and FastPath options (see above). 117 118## Running tests with QEMU for cross-compiled aarch64/arm builds 119 120Recommended QEMU version for running tests is 6.2.0 (but 5.1+ should be ok, too). By default, it is downloaded and installed during environment bootstrap. Any system-installed package is left intact. If recommended QEMU version is not accessible via $PATH it can be specified during configuration time: 121 122``` 123# If QEMU is available as /opt/qemu-6.2.0/bin/qemu-aarch64 124$ cmake -DQEMU_PREFIX=/opt/qemu-6.2.0 ... 125``` 126 127## Building with GN 128 129### Using bootstrap 130 131Build `arkts_bin`, `ark_aot`, `es2panda`, `verifier_bin` and `ets_interop_js_napi` targets. 132``` 133./scripts/build-panda-with-gn 134``` 135 136### Mannually 137 1381. Getting GN binary 139 140``` 141$ git clone https://gn.googlesource.com/gn 142$ cd gn 143$ python build/gen.py 144$ ninja -C out 145``` 146 1472. Build panda using gn (`arkts_asm`, `arkts_disasm`, `ark_aot`, `ark_aotdump`, `arkts_bin`, `es2panda`, and `verifier_bin` targets are supported) 148 149``` 150$ cd /path/to/panda/repository 151$ /path/to/gn/repository/out/gn gen out 152$ ninja -C out arkts_bin 153``` 154When standard system, use 155``` 156$ cd /path/to/panda/repository 157$ /path/to/gn/repository/out/gn --args=is_standard_system=true gen out 158$ ninja -C out <target name> 159``` 160To use LLVM Backend add the following arguments: 161``` 162$ /path/to/gn/repository/out/gn out is_llvmbackend=true llvm_target_dir="/opt/llvm-15-{type}-{arch}" ... 163``` 164Setting `is_llvmbackend=true` option enables the same scenarios as `-DPANDA_LLVM_BACKEND=true` option in cmake builds 165 166## Further reading 167 168* For more details, please see [build system readme](cmake/README.md). 169 170# Testing 171 172For testing, the following umbrella targets that guarantee building prior to running may be used: 173 174* `tests`, for running all testing suites. 175* `tests_full`, for running all testing suites and various code linters. 176 177# Clang tools 178 179`clang-format` and `clang-tidy` checks are integrated into build system and can be called by target of build system: 180``` 181$ ninja code-style-check # clang-format 182$ ninja clang-tidy-check # clang-tidy 183``` 184 185# Test coverage 186 187In order to measure bytecode optimizer coverage, configure your build with -DENABLE_BYTECODE_OPTIMIZER_COVERAGE=true. Then run: 188``` 189$ ninja bytecode_optimizer_coverage 190``` 191 192# Benchmarking 193 194To build and run benchmarks, please use the umbrella target `benchmarks` or any of its 195dependencies. Please see the root `CMakeLists.txt` for more details. 196 197NB! Make sure that you configure your build with `-DCMAKE_BUILD_TYPE=Release`, otherwise 198your run will most likely be dead slow. 199 200# Running 201 202## Running assembler 203 204Assuming that you are in `panda-build` directory, please run: 205 206``` 207$ ./bin/ark_asm /path/to/panda-assembly.pa /path/to/binary/output.abc 208``` 209 210## Running interpreter 211 212Assuming that your main function is defined as `.function main(...)` in the assembly listing, 213and `/path/to/binary/output.abc` is the result of the assembler, please run: 214 215``` 216$ ./bin/ark /path/to/binary/output.abc _GLOBAL::main 217``` 218