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 1291. Getting GN binary 130 131``` 132$ git clone https://gn.googlesource.com/gn 133$ cd gn 134$ python build/gen.py 135$ ninja -C out 136``` 137 1382. Build panda using gn (`arkts_asm`, `arkts_disasm`, `ark_aot`, `ark_aotdump`, `arkts_bin`, `es2panda`, and `verifier_bin` targets are supported) 139 140``` 141$ cd /path/to/panda/repository 142$ /path/to/gn/repository/out/gn gen out 143$ ninja -C out arkts_bin 144``` 145When standard system, use 146``` 147$ cd /path/to/panda/repository 148$ /path/to/gn/repository/out/gn --args=-is_standard_system=true gen out 149$ ninja -C out <target name> 150``` 151To use LLVM Backend add the following arguments: 152``` 153$ /path/to/gn/repository/out/gn out is_llvmbackend=true llvm_target_dir="/opt/llvm-15-{type}-{arch}" ... 154``` 155Setting `is_llvmbackend=true` option enables the same scenarios as `-DPANDA_LLVM_BACKEND=true` option in cmake builds 156 157## Further reading 158 159* For more details, please see [build system readme](cmake/README.md). 160 161# Testing 162 163For testing, the following umbrella targets that guarantee building prior to running may be used: 164 165* `tests`, for running all testing suites. 166* `tests_full`, for running all testing suites and various code linters. 167 168# Clang tools 169 170`clang-format` and `clang-tidy` checks are integrated into build system and can be called by target of build system: 171``` 172$ ninja code-style-check # clang-format 173$ ninja clang-tidy-check # clang-tidy 174``` 175 176# Test coverage 177 178In order to measure bytecode optimizer coverage, configure your build with -DENABLE_BYTECODE_OPTIMIZER_COVERAGE=true. Then run: 179``` 180$ ninja bytecode_optimizer_coverage 181``` 182 183# Benchmarking 184 185To build and run benchmarks, please use the umbrella target `benchmarks` or any of its 186dependencies. Please see the root `CMakeLists.txt` for more details. 187 188NB! Make sure that you configure your build with `-DCMAKE_BUILD_TYPE=Release`, otherwise 189your run will most likely be dead slow. 190 191# Running 192 193## Running assembler 194 195Assuming that you are in `panda-build` directory, please run: 196 197``` 198$ ./bin/ark_asm /path/to/panda-assembly.pa /path/to/binary/output.abc 199``` 200 201## Running interpreter 202 203Assuming that your main function is defined as `.function main(...)` in the assembly listing, 204and `/path/to/binary/output.abc` is the result of the assembler, please run: 205 206``` 207$ ./bin/ark /path/to/binary/output.abc _GLOBAL::main 208``` 209