diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.md | 218 |
1 files changed, 168 insertions, 50 deletions
diff --git a/doc/build.md b/doc/build.md index 7e4cc7c..18165b7 100644 --- a/doc/build.md +++ b/doc/build.md @@ -1,44 +1,108 @@ # Building cpsc -Run these commands from the project root unless stated otherwise. For installation and release packaging, see [install.md](install.md). +Run these commands from the project root. For installation and release packaging, +see [install.md](install.md). ## Dependencies -These are build dependencies. All three modes use LLVM to generate IR, so even -`NONE` requires LLVM development libraries when building the compiler. -Users of an `EMBEDDED` executable do not need to install LLVM or `lli`. +Install CMake, make and Clang as system tools. Download the other dependencies to +`build/deps/packages/`; CMake extracts them into `build/deps/root/` during +configuration. Each dependency is searched locally first, then in the system. +Local LLVM takes precedence over a previously cached system `LLVM_DIR`. + +Unchanged packages are not extracted again. Keep one version of each package in +the download directory; remove old archives before downloading a different +version. CMake rebuilds its extraction directory when the package set changes. +If you use a different CMake build directory, download into its `deps/packages/` +instead. Removing the build directory also removes its downloaded dependencies. + +All three execution modes need LLVM development libraries to build, including +`NONE`. Users of an `EMBEDDED` executable do not need LLVM or `lli`. +LLVM 18 is the tested version; newer versions remain untested. + +### Linux (Debian/Ubuntu) + +Use a distribution repository that provides LLVM 18. Install the build tools: -Linux ```bash sudo apt-get update -sudo apt-get install -y \ - build-essential \ - cmake \ - llvm-18-dev \ - zlib1g-dev \ - libzstd-dev \ - libtinfo-dev +sudo apt-get install -y --no-install-recommends build-essential cmake clang-18 +``` + +Download LLVM and its support packages without installing them: + +```bash +mkdir -p build/deps/packages +( + cd build/deps/packages + apt-get download \ + llvm-18-dev llvm-18 llvm-18-runtime llvm-18-tools llvm-18-linker-tools \ + libllvm18 libclang-cpp18 libz3-dev libz3-4 \ + libffi-dev libffi8 libxml2-dev libxml2 \ + zlib1g-dev zlib1g libzstd-dev libzstd1 libncurses-dev libtinfo6 +) ``` -The last three packages supply static support archives for `EMBEDDED` when the -LLVM package uses them. `PATH` additionally needs `lli` at run time, for example -from `llvm-18` with `/usr/lib/llvm-18/bin` in PATH. Clang is only needed if you -want to turn the emitted IR into a native executable yourself. +`apt-get download` also downloads explicitly named packages that are already +installed. The LLVM companion packages satisfy its CMake imports, while the +development support packages supply the static archives used by `EMBEDDED`. ---- +### Windows (MSYS2 MINGW64) + +Run these commands in the MSYS2 **MINGW64** shell. Update MSYS2 first, reopening +the shell and repeating the update if requested: -mingw-w64 for Windows ```bash pacman -Syu pacman -S --needed \ - mingw-w64-x86_64-toolchain \ mingw-w64-x86_64-cmake \ + mingw-w64-x86_64-make \ + mingw-w64-x86_64-clang +``` + +Download the dependencies to the project build directory: + +```bash +mkdir -p build/deps/packages +pacman -Sw --noconfirm --cachedir "$PWD/build/deps/packages" \ mingw-w64-x86_64-llvm \ - mingw-w64-x86_64-clang \ + mingw-w64-x86_64-llvm-libs \ + mingw-w64-x86_64-llvm-tools \ mingw-w64-x86_64-lld \ - mingw-w64-x86_64-make + mingw-w64-x86_64-libffi \ + mingw-w64-x86_64-libxml2 \ + mingw-w64-x86_64-libiconv \ + mingw-w64-x86_64-zlib \ + mingw-w64-x86_64-zstd ``` +`-Sw` downloads packages without installing them; omit `--needed` here so that +already installed dependencies are also downloaded. CMake keeps the packages' +`mingw64/` layout under `build/deps/root/`. MSYS2 supplies its current LLVM +version. Windows builds have only been reviewed statically. + +### macOS (Homebrew) + +Use Clang and make from the Xcode Command Line Tools. If they are missing, run +`xcode-select --install`. Install CMake with Homebrew: + +```bash +brew install cmake +``` + +Download the binary bottles to the build directory: + +```bash +mkdir -p build/deps/packages +HOMEBREW_CACHE="$PWD/build/deps/packages" brew fetch --force-bottle \ + llvm@18 zlib zstd ncurses lz4 xz +``` + +This requires binary bottles available for your macOS version and CPU; source +archives are not used. CMake extracts the bottles into a local `Cellar/`, creates +local `opt/` links and relocates their CMake and dynamic-library paths using the +Command Line Tools. The macOS build has only been reviewed statically. + ## Build You must explicitly choose `-DCPSC_RUN_MODE=PATH`, `EMBEDDED`, or `NONE` on @@ -50,54 +114,108 @@ initial configuration; there is no default. The choice is saved in CMake's cache | `EMBEDDED` | Run with the statically linked LLVM engine inside `cpsc`; no PATH lookup. | | `NONE` | Reject `-r`; compiling to IR still works. | -Linux +Linux: + ```bash -cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED \ - -DLLVM_DIR=/usr/lib/llvm-18/cmake -DCMAKE_BUILD_TYPE=Release +cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_C_COMPILER=clang-18 -DCMAKE_CXX_COMPILER=clang++-18 cmake --build build -j4 ``` -Distribute `build/cpsc` for `EMBEDDED`. LLVM, the project's libraries and the -compression/terminal support libraries are linked statically; a missing required -archive is a configure error. On Linux with GCC/Clang, the C++ runtime is static -too. The tested Debian/LLVM 18 executable needs only the system libc, libm and -dynamic loader. It runs pseudocode with `-r` as one executable, without LLVM -libraries or `lli` installed. Build for the intended operating system and CPU. +MSYS2 MINGW64: ---- +```bash +cmake -S . -B build -G "MinGW Makefiles" \ + -DCPSC_RUN_MODE=EMBEDDED -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ +mingw32-make -C build -j4 +``` + +macOS: -mingw-w64 for Windows ```bash -mkdir build && cd build/ -export CMAKE_GENERATOR="MinGW Makefiles" -cmake -DCPSC_RUN_MODE=EMBEDDED .. -mingw32-make +cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++ +cmake --build build -j4 ``` -MinGW uses static linking for `EMBEDDED`; this mode has been verified on Linux, -and the Windows build has not been tested. +Local packages do not need `-DLLVM_DIR`. When no local LLVM is present, CMake uses +the system search; you can specify `-DLLVM_DIR=/path/to/lib/cmake/llvm` for a +system installation outside its usual search paths. + +Distribute `build/cpsc` (Windows: `build/cpsc.exe`) for `EMBEDDED`. LLVM and its +required compression/terminal support libraries are linked statically; a missing +required archive is a configure error. Linux also links the C++ runtime statically, +and MinGW uses static linking. The tested Debian/LLVM 18 executable needs only +the system libc, libm and dynamic loader. Build for the intended OS and CPU. + +For `PATH` mode, add the extracted `lli` directory to your shell's PATH after +configuration. On Linux, also expose its downloaded runtime libraries: + +```bash +export PATH="$PWD/build/deps/root/usr/lib/llvm-18/bin:$PATH" +export LD_LIBRARY_PATH="$PWD/build/deps/root/usr/lib/$(cc -print-multiarch)${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" +``` + +MSYS2 MINGW64: + +```bash +export PATH="$PWD/build/deps/root/mingw64/bin:$PATH" +``` + +macOS: + +```bash +export PATH="$PWD/build/deps/root/opt/llvm@18/bin:$PATH" +``` ## Manual -The command-line quick reference is in [cpsc.md](cpsc.md). Generating the manual requires Pandoc; ordinary builds do not. +The quick reference is in [cpsc.md](cpsc.md). Pandoc is required only for the +`doc`, installation and release targets. Download it for your platform: + +Linux: -From the project root on Linux: +```bash +( + cd build/deps/packages + apt-get download pandoc pandoc-data \ + libffi8 libgmp10 liblua5.4-0 libnuma1 libyaml-0-2 zlib1g +) +``` + +macOS: ```bash -sudo apt-get install pandoc -cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED -make -C build doc -man ./build/doc/cpsc.1 +HOMEBREW_CACHE="$PWD/build/deps/packages" brew fetch --force-bottle pandoc gmp ``` -You can also run `make doc` inside the configured `build/` directory. -The output is `build/doc/cpsc.1` on Unix and `build/doc/cpsc.html` on Windows, -and is regenerated when the Markdown source changes. On Windows, install Pandoc, -then generate and open the standalone HTML manual from PowerShell: +Windows has no MSYS2 Pandoc package. Download the official x86_64 ZIP from +PowerShell, without running an installer: ```powershell +New-Item -ItemType Directory -Force build/deps/packages | Out-Null +$release = Invoke-RestMethod https://api.github.com/repos/jgm/pandoc/releases/latest +$asset = $release.assets | Where-Object { $_.name -like 'pandoc-*-windows-x86_64.zip' } +Invoke-WebRequest -UseBasicParsing $asset.browser_download_url -OutFile "build/deps/packages/$($asset.name)" +``` + +The ZIP is provided on the [official Pandoc download page](https://pandoc.org/installing.html). + +Reconfigure using your platform's build command above, then generate the manual: + +```bash cmake --build build --target doc -Start-Process .\build\doc\cpsc.html ``` -The HTML contains its own styles and can be read offline in a browser. +CMake selects local Pandoc first, sets its local runtime/data paths as needed, +and falls back to Pandoc in the system PATH. The output is `build/doc/cpsc.1` on +Unix and `build/doc/cpsc.html` on Windows. It is regenerated when the source or +downloaded packages change. + +On Unix, open it with `man ./build/doc/cpsc.1`. On Windows, open the standalone, +offline HTML from PowerShell: + +```powershell +Start-Process .\build\doc\cpsc.html +``` |