Documentation: Update Build instructions for new and removed features

Removed options, the fact that the CMakePresests.json exists, etc.
This commit is contained in:
Andrew Kaster 2024-06-04 15:10:48 -06:00 committed by Tim Flynn
parent 90af26e309
commit f234429392
Notes: sideshowbarker 2024-07-16 19:17:47 +09:00
2 changed files with 20 additions and 43 deletions

View file

@ -11,7 +11,6 @@ directory to `Build/ladybird` and then running `ninja <target>`:
- `ninja check-style`: Runs the same linters the CI does to verify project style on changed files
- `ninja lint-shell-scripts`: Checks style of shell scripts in the source tree with shellcheck
- `ninja all_generated`: Builds all generated code. Useful for running analysis tools that can use compile_commands.json without a full system build
- `ninja configure-components`: See the [Component Configuration](#component-configuration) section below.
## CMake build options
@ -28,12 +27,8 @@ There are some optional features that can be enabled during compilation that are
- `ENABLE_COMPILETIME_FORMAT_CHECK`: checks for the validity of `std::format`-style format string during compilation. Enabled by default.
- `BUILD_LAGOM`: builds [Lagom](../Meta/Lagom/ReadMe.md), which makes various SerenityOS libraries and programs available on the host system.
- `ENABLE_MOLD_LINKER`: builds the userland with the [`mold` linker](https://github.com/rui314/mold). `mold` can be built by running `Toolchain/BuildMold.sh`.
- `ENABLE_JAKT`: builds the `jakt` compiler as a Lagom host tool and enables building applications and libraries that are written in the jakt language.
- `JAKT_SOURCE_DIR`: `jakt` developer's local checkout of the jakt programming language for rapid testing. To use a local checkout, set to an absolute path when changing the CMake cache of Lagom. e.g. ``cmake -S Meta/Lagom -B Build/lagom -DENABLE_JAKT=ON -DJAKT_SOURCE_DIR=/home/me/jakt``
- `INCLUDE_WASM_SPEC_TESTS`: downloads and includes the WebAssembly spec testsuite tests. In order to use this option, you will need to install `prettier` and `wabt`. wabt version 1.0.23 or higher is required to pre-process the WebAssembly spec testsuite.
- `INCLUDE_FLAC_SPEC_TESTS`: downloads and includes the xiph.org FLAC test suite.
- `BUILD_<component>`: builds the specified component, e.g. `BUILD_HEARTS` (note: must be all caps). Check the components.ini file in your build directory for a list of available components. Make sure to run `ninja clean` and `rm -rf Build/x86_64/Root` after disabling components. These options can be easily configured by using the `ConfigureComponents` utility. See the [Component Configuration](#component-configuration) section below.
- `BUILD_EVERYTHING`: builds all optional components, overrides other `BUILD_<component>` flags when enabled
- `SERENITY_CACHE_DIR`: sets the location of a shared cache of downloaded files. Should not need to be set unless managing a distribution package.
- `ENABLE_NETWORK_DOWNLOADS`: allows downloading files from the internet during the build. Default on, turning off enables offline builds. For offline builds, the structure of the SERENITY_CACHE_DIR must be set up the way that the build expects.
- `ENABLE_ACCELERATED_GRAPHICS`: builds features that use accelerated graphics APIs to speed up painting and drawing using native graphics libraries.
@ -64,17 +59,6 @@ $ cmake -B Build/ladbyird -DPROCESS_DEBUG=ON
For more information on how the CMake cache works, see the CMake guide for [Running CMake](https://cmake.org/runningcmake/). Additional context is available in the CMake documentation for
[variables](https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#variables) and [set()](https://cmake.org/cmake/help/latest/command/set.html#set-cache-entry).
## Component Configuration
For selecting which components of the system to build and install, a helper program, `ConfigureComponents` is available.
It requires `whiptail` as a dependency, which is available on most systems in the `newt` or `libnewt` package. To build and run it, run the following commands from the `Build/x86_64` directory:
```console
$ ninja configure-components
```
This will prompt you which build type you want to use and allows you to customize it by manually adding or removing certain components. It will then run a CMake command based on the selection as well as `ninja clean` and `rm -rf Root` to remove old build artifacts.
## Tests
For information on running host and target tests, see [Running Tests](RunningTests.md). The documentation there also contains useful information for debugging CI test failures.

View file

@ -109,7 +109,7 @@ Qt chrome, install the Qt dependencies for your platform, and enable the Qt chro
```bash
# From /path/to/ladybird
cmake -B Build/ladybird -DENABLE_QT=ON
cmake --preset default -DENABLE_QT=ON
```
To re-disable the Qt chrome, run the above command with `-DENABLE_QT=OFF`.
@ -117,18 +117,16 @@ To re-disable the Qt chrome, run the above command with `-DENABLE_QT=OFF`.
### Resource files
Ladybird requires resource files from the ladybird/Base/res directory in order to properly load
icons, fonts, and other theming information. The ladybird.sh script calls into custom CMake targets
that set these variables, and ensure that the $PWD is set properly to allow execution from the build
directory. To run the built binary without using the script, one can either directly invoke the
ninja rules or install ladybird using the provided CMake install rules. See the ``Custom CMake build directory``
section below for details.
icons, fonts, and other theming information. These files are copied into the build directory by
special CMake rules. The expected location of resource files can be tweaked by packagers using
the standard CMAKE_INSTALL_DATADIR variable. CMAKE_INSTALL_DATADIR is expected to be a path relative
to CMAKE_INSTALL_PREFIX. If it is not, things will break.
### Custom CMake build directory
If you want to build ladybird on its own, or are interested in packaging ladybird for distribution,
then a separate CMake build directory may be desired. Note that ladybird can be build via the Lagom
CMakeLists.txt, or via the CMakeLists.txt found in the Ladybird directory. For distributions, using
Ladybird as the source directory will give the desired results.
The script Meta/ladybird.sh and the default preset in CMakePresets.json both define a build directory of
`Build/ladybird`. For distribution purposes, or when building multiple configurations, it may be useful to create a custom
CMake build directory.
The install rules in Ladybird/cmake/InstallRules.cmake define which binaries and libraries will be
installed into the configured CMAKE_PREFIX_PATH or path passed to ``cmake --install``.
@ -138,15 +136,20 @@ a suitable C++ compiler (g++ >= 13, clang >= 14, Apple Clang >= 14.3) via the CM
CMAKE_C_COMPILER cmake options.
```
cmake -GNinja -B Build/ladybird
cmake -GNinja -B MyBuildDir
# optionally, add -DCMAKE_CXX_COMPILER=<suitable compiler> -DCMAKE_C_COMPILER=<matching c compiler>
cmake --build Build/ladybird
ninja -C Build/ladybird run
cmake --build MyBuildDir
ninja -C MyBuildDir run-ladybird
```
### Running manually
The Meta/ladybird.sh script will execute the `run-ladybird` and `debug-ladybird` custom targets.
If you don't want to use the ladybird.sh script to run the application, you can run the following commands:
To automatically run in gdb:
```
ninja -C Build/ladybird debug
ninja -C Build/ladybird debug-ladybird
```
To run without ninja rule on non-macOS systems:
@ -173,9 +176,10 @@ cross-compiling to other platforms.
### Debugging with CLion
Ladybird should be built with debug symbols first. In `Meta/CMake/lagom_compile_options.cmake` remove the optimizations by changing `-O2` to `-O0`. For macOS also change the debug option from `-g1` to `-g` so that lldb is happy with the emitted symbols. In linux `-g1` can be changed to `-ggdb3` for maximum debug info.
Ladybird should be built with debug symbols first. This can be done by adding `-DCMAKE_BUILD_TYPE=Debug` to the cmake command line,
or selecting the Build Type Debug in the CLion CMake profile.
After running Ladybird as suggested above with `./Meta/ladybird.sh run ladybird`, you can now in CLion use Run -> Attach to Process to connect. If debugging layouting and rendering issues, filter the listing that opens for `WebContent` and attach to that.
After running Ladybird as suggested above with `./Meta/ladybird.sh run ladybird`, you can now in CLion use Run -> Attach to Process to connect. If debugging layout or rendering issues, filter the listing that opens for `WebContent` and attach to that.
Now breakpoints, stepping and variable inspection will work.
@ -206,14 +210,3 @@ CMAKE_PREFIX_PATH=/usr/lib/qt/6.2/lib/amd64/cmake cmake -GNinja -B Build/ladybir
cmake --build Build/ladybird
XDG_RUNTIME_DIR=/var/tmp ninja -C Build/ladybird run
```
### Building on Haiku
Haiku is supported by Ladybird out of the box. The steps are the same as on OpenIndiana, but no
additional environment variables are required.
```
cmake -GNinja -B Build/ladybird
cmake --build Build/ladybird
ninja -C Build/ladybird run
```