mirror of
https://github.com/LadybirdBrowser/ladybird.git
synced 2024-11-25 00:50:22 +00:00
Documentation: Remove references to serenity.sh and its build configs
Build/lagom only now.
This commit is contained in:
parent
faeff81ce9
commit
9dd24991a8
Notes:
sideshowbarker
2024-07-17 03:00:02 +09:00
Author: https://github.com/ADKaster Commit: https://github.com/LadybirdBrowser/ancient-history/commit/9dd24991a8
15 changed files with 70 additions and 195 deletions
|
@ -4,7 +4,7 @@ This file covers a few advanced scenarios that go beyond what the basic build gu
|
||||||
|
|
||||||
## Ninja build targets
|
## Ninja build targets
|
||||||
|
|
||||||
The `Meta/serenity.sh` script provides an abstraction over the build targets which are made available by CMake. The
|
The `Meta/ladybird.sh` script provides an abstraction over the build targets which are made available by CMake. The
|
||||||
following build targets cannot be accessed through the script and have to be used directly by changing the current
|
following build targets cannot be accessed through the script and have to be used directly by changing the current
|
||||||
directory to `Build/x86_64` and then running `ninja <target>`:
|
directory to `Build/x86_64` and then running `ninja <target>`:
|
||||||
|
|
||||||
|
|
|
@ -146,9 +146,9 @@ is present and code should be placed in `Bindings/`.
|
||||||
Every feature or bug fix added to LibWeb should have a corresponding test in `Tests/LibWeb`.
|
Every feature or bug fix added to LibWeb should have a corresponding test in `Tests/LibWeb`.
|
||||||
The test should be either a Text, Layout or Ref test depending on the feature.
|
The test should be either a Text, Layout or Ref test depending on the feature.
|
||||||
|
|
||||||
LibWeb tests can be run in one of two ways. The easiest is to use the `serenity.sh` script. The LibWeb tests are
|
LibWeb tests can be run in one of two ways. The easiest is to use the `ladybird.sh` script. The LibWeb tests are
|
||||||
registered with CMake as a test in `Ladybird/CMakeLists.txt`. Using the builtin test filtering, you can run all tests
|
registered with CMake as a test in `Ladybird/CMakeLists.txt`. Using the builtin test filtering, you can run all tests
|
||||||
with `Meta/serenity.sh test lagom` or run just the LibWeb tests with `Meta/serenity.sh test lagom LibWeb`. The second
|
with `Meta/ladybird.sh test` or run just the LibWeb tests with `Meta/ladybird.sh test LibWeb`. The second
|
||||||
way is to invoke the headless browser test runner directly. See the invocation in `Ladybird/CMakeLists.txt` for the
|
way is to invoke the headless browser test runner directly. See the invocation in `Ladybird/CMakeLists.txt` for the
|
||||||
expected command line arguments.
|
expected command line arguments.
|
||||||
|
|
||||||
|
|
|
@ -89,14 +89,14 @@ Or, download a version of Gradle >= 8.0.0, and run the ``gradlew`` program in ``
|
||||||
|
|
||||||
## Build steps
|
## Build steps
|
||||||
|
|
||||||
### Using serenity.sh
|
### Using ladybird.sh
|
||||||
|
|
||||||
The simplest way to build and run ladybird is via the serenity.sh script:
|
The simplest way to build and run ladybird is via the ladybird.sh script:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# From /path/to/ladybird
|
# From /path/to/ladybird
|
||||||
./Meta/serenity.sh run lagom ladybird
|
./Meta/ladybird.sh run ladybird
|
||||||
./Meta/serenity.sh gdb lagom ladybird
|
./Meta/ladybird.sh gdb ladybird
|
||||||
```
|
```
|
||||||
|
|
||||||
The above commands will build Ladybird with one of the following browser chromes, depending on the platform:
|
The above commands will build Ladybird with one of the following browser chromes, depending on the platform:
|
||||||
|
@ -114,15 +114,6 @@ cmake -S Meta/Lagom -B Build/lagom -DENABLE_QT=ON
|
||||||
|
|
||||||
To re-disable the Qt chrome, run the above command with `-DENABLE_QT=OFF`.
|
To re-disable the Qt chrome, run the above command with `-DENABLE_QT=OFF`.
|
||||||
|
|
||||||
### Disabling Ladybird
|
|
||||||
|
|
||||||
Note that running ladybird from the script will change the CMake cache in your Build/lagom build
|
|
||||||
directory to always build LibWeb and Ladybird for Lagom when rebuilding SerenityOS using the
|
|
||||||
serenity.sh script to run a qemu instance.
|
|
||||||
|
|
||||||
To restore the previous behavior that only builds code generators and tools from Lagom when
|
|
||||||
rebuilding serenity, you must modify the CMake cache back to the default.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cmake -S Meta/Lagom -B Build/lagom -DENABLE_LAGOM_LADYBIRD=OFF -DENABLE_LAGOM_LIBWEB=OFF -DBUILD_LAGOM=OFF
|
cmake -S Meta/Lagom -B Build/lagom -DENABLE_LAGOM_LADYBIRD=OFF -DENABLE_LAGOM_LIBWEB=OFF -DBUILD_LAGOM=OFF
|
||||||
```
|
```
|
||||||
|
@ -130,7 +121,7 @@ cmake -S Meta/Lagom -B Build/lagom -DENABLE_LAGOM_LADYBIRD=OFF -DENABLE_LAGOM_LI
|
||||||
### Resource files
|
### Resource files
|
||||||
|
|
||||||
Ladybird requires resource files from the ladybird/Base/res directory in order to properly load
|
Ladybird requires resource files from the ladybird/Base/res directory in order to properly load
|
||||||
icons, fonts, and other theming information. The serenity.sh script calls into custom CMake targets
|
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
|
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
|
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``
|
ninja rules or install ladybird using the provided CMake install rules. See the ``Custom CMake build directory``
|
||||||
|
@ -146,7 +137,7 @@ Ladybird as the source directory will give the desired results.
|
||||||
The install rules in Ladybird/cmake/InstallRules.cmake define which binaries and libraries will be
|
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``.
|
installed into the configured CMAKE_PREFIX_PATH or path passed to ``cmake --install``.
|
||||||
|
|
||||||
Note that when using a custom build directory rather than Meta/serenity.sh, the user may need to provide
|
Note that when using a custom build directory rather than Meta/ladybird.sh, the user may need to provide
|
||||||
a suitable C++ compiler (g++ >= 13, clang >= 14, Apple Clang >= 14.3) via the CMAKE_CXX_COMPILER and
|
a suitable C++ compiler (g++ >= 13, clang >= 14, Apple Clang >= 14.3) via the CMAKE_CXX_COMPILER and
|
||||||
CMAKE_C_COMPILER cmake options.
|
CMAKE_C_COMPILER cmake options.
|
||||||
|
|
||||||
|
@ -188,20 +179,20 @@ cross-compiling to other platforms.
|
||||||
|
|
||||||
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. 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.
|
||||||
|
|
||||||
After running Ladybird as suggested above with `./Meta/serenity.sh run lagom 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 layouting and rendering issues, filter the listing that opens for `WebContent` and attach to that.
|
||||||
|
|
||||||
Now breakpoints, stepping and variable inspection will work.
|
Now breakpoints, stepping and variable inspection will work.
|
||||||
|
|
||||||
### Debugging with Xcode on macOS
|
### Debugging with Xcode on macOS
|
||||||
|
|
||||||
The `serenity.sh` build script does not know how to generate Xcode projects, so creating the project must be done manually.
|
The `ladybird.sh` build script does not know how to generate Xcode projects, so creating the project must be done manually.
|
||||||
To be compatible with the `serenity.sh` script, a few extra options are required. If there is a previous Lagom build directory, CMake will likely complain that the generator has changed.
|
To be compatible with the `ladybird.sh` script, a few extra options are required. If there is a previous Lagom build directory, CMake will likely complain that the generator has changed.
|
||||||
|
|
||||||
```
|
```
|
||||||
cmake -GXcode -S Meta/Lagom -B Build/lagom -DBUILD_LAGOM=ON -DENABLE_LAGOM_LADYBIRD=ON
|
cmake -GXcode -S Meta/Lagom -B Build/lagom -DBUILD_LAGOM=ON -DENABLE_LAGOM_LADYBIRD=ON
|
||||||
```
|
```
|
||||||
|
|
||||||
Alternatively, if you don't need your ladybird build to be compatible with `serenity.sh`, you can use Ladybird as the source directory like so:
|
Alternatively, if you don't need your ladybird build to be compatible with `ladybird.sh`, you can use Ladybird as the source directory like so:
|
||||||
|
|
||||||
```
|
```
|
||||||
cmake -GXcode -S Ladybird -B Build/ladybird
|
cmake -GXcode -S Ladybird -B Build/ladybird
|
||||||
|
|
|
@ -4,29 +4,15 @@ CLion can integrate with CMake to provide code comprehension features.
|
||||||
|
|
||||||
After opening the `ladybird` repository in CLion as a new project, the "`Open Project Wizard`" window will open, from here set the following fields:
|
After opening the `ladybird` repository in CLion as a new project, the "`Open Project Wizard`" window will open, from here set the following fields:
|
||||||
|
|
||||||
(Assuming you use `Ninja` as the build system and configured the CMake build directory to `Build/x86_64`)
|
(Assuming you use `Ninja` as the build system and configured the CMake build directory to `Build/lagom`)
|
||||||
|
|
||||||
`Build type`: `Default`
|
|
||||||
|
|
||||||
> _CMake will complain with any other build type, make sure to use `Default` so that `CMAKE_BUILD_TYPE` is empty in the `Build/x86_64/CMakeCache.txt` file._
|
|
||||||
|
|
||||||
`CMake Options`:
|
`CMake Options`:
|
||||||
```
|
```
|
||||||
-DCMAKE_PREFIX_PATH=$CMakeProjectDir$/Build/lagom-install
|
|
||||||
-DCMAKE_TOOLCHAIN_FILE=$CMakeProjectDir$/Build/x86_64/CMakeToolchain.txt
|
|
||||||
-DSERENITY_ARCH=x86_64
|
|
||||||
-DSERENITY_CACHE_DIR=$CMakeProjectDir$/Build/caches
|
-DSERENITY_CACHE_DIR=$CMakeProjectDir$/Build/caches
|
||||||
-GNinja
|
-GNinja
|
||||||
```
|
```
|
||||||
|
|
||||||
> CLion will complain that the toolchain file doesn't exist yet, if you haven't `cmake` for the SuperBuild step before. The SuperBuild configure step creates the Toolchain file.
|
`Build Directory`: `Build/lagom`
|
||||||
> To re-create the file after blasting your build directory, run `cmake -GNinja -S Meta/CMake/Superbuild -B Build/superbuild-x86_64` from the top level in a terminal, or simply run `./Meta/serenity.sh run`
|
|
||||||
|
|
||||||
`Build Directory`: `Build/x86_64`
|
|
||||||
|
|
||||||
> _If you have not built the Toolchain at this point, please do so: `./Toolchain/BuildGNU.sh`_
|
|
||||||
|
|
||||||
> _If you have not built host tools from Lagom at this point, please do so: `./Meta/serenity.sh build` or `ninja -C Build/superbuild-x86_64` after running `cmake -GNinja -S Meta/CMake/Superbuild -B Build/superbuild-x86_64`_
|
|
||||||
|
|
||||||
If you already have the project open, you can go to `File -> Settings -> Build, Execution, Deployment -> CMake` to find these options.
|
If you already have the project open, you can go to `File -> Settings -> Build, Execution, Deployment -> CMake` to find these options.
|
||||||
|
|
||||||
|
@ -34,11 +20,7 @@ If you already have the project open, you can go to `File -> Settings -> Build,
|
||||||
|
|
||||||
Source files are copied to the `Build` directory during the build, if you do not exclude them from CLion indexing they will show up
|
Source files are copied to the `Build` directory during the build, if you do not exclude them from CLion indexing they will show up
|
||||||
in search results. This is often confusing, unintuitive, and can result in you losing changes you have made to files. To exclude
|
in search results. This is often confusing, unintuitive, and can result in you losing changes you have made to files. To exclude
|
||||||
these files navigate to the `Project` tool window, right-click the `Build` folder and select `Mark Directory as | Excluded`. If you
|
these files navigate to the `Project` tool window, right-click the `Build` folder and select `Mark Directory as | Excluded`.
|
||||||
want to exclude Toolchain files as well, follow the same procedure with the following paths:
|
|
||||||
- `Toolchain/Local`
|
|
||||||
- `Toolchain/Tarballs`
|
|
||||||
- `Toolchain/Build`
|
|
||||||
|
|
||||||
## Include headers and source files for code insight
|
## Include headers and source files for code insight
|
||||||
|
|
||||||
|
|
|
@ -9,12 +9,7 @@ can use the following `.clangd` file placed in the project root:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
CompileFlags:
|
CompileFlags:
|
||||||
CompilationDatabase: Build/x86_64
|
CompilationDatabase: Build/lagom
|
||||||
Add:
|
|
||||||
- "-D__serenity__"
|
|
||||||
- "-UNO_TLS"
|
|
||||||
- "-I/path/to/ladybird/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/13.1.0"
|
|
||||||
- "-I/path/to/ladybird/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/13.1.0/x86_64-pc-serenity"
|
|
||||||
|
|
||||||
Diagnostics:
|
Diagnostics:
|
||||||
UnusedIncludes: None
|
UnusedIncludes: None
|
||||||
|
@ -24,8 +19,8 @@ Diagnostics:
|
||||||
You will need to change `/path/to/ladybird` and change `13.1.0` to
|
You will need to change `/path/to/ladybird` and change `13.1.0` to
|
||||||
whatever your GCC toolchain version at the time is.
|
whatever your GCC toolchain version at the time is.
|
||||||
|
|
||||||
Run cmake (`Meta/serenity.sh run` or similar) at least once for this
|
Run cmake (`Meta/ladybird.sh run ladybird` or similar) at least once for this
|
||||||
to work, as it will generate the `Build/x86_64/compile_commands.json`
|
to work, as it will generate the `Build/lagom/compile_commands.json`
|
||||||
that is needed by `clangd`.
|
that is needed by `clangd`.
|
||||||
|
|
||||||
### lsp-mode
|
### lsp-mode
|
||||||
|
|
|
@ -4,7 +4,7 @@ This is not about web event loops, which are a separate LibWeb concept.
|
||||||
|
|
||||||
For handling application tasks concurrently on one thread, LibCore provides the `EventLoop` system. The event loop is found in many systems, and it can be briefly summarized as an in-process loop, running all the time, which processes incoming events from signals, notifiers, file watchers, timers etc. by running associated callbacks. The event loop relies on the fact that the callbacks will eventually return control to it, so that other events can be processed. In that way, it's like a cooperative multitasking scheduler in userspace.
|
For handling application tasks concurrently on one thread, LibCore provides the `EventLoop` system. The event loop is found in many systems, and it can be briefly summarized as an in-process loop, running all the time, which processes incoming events from signals, notifiers, file watchers, timers etc. by running associated callbacks. The event loop relies on the fact that the callbacks will eventually return control to it, so that other events can be processed. In that way, it's like a cooperative multitasking scheduler in userspace.
|
||||||
|
|
||||||
SerenityOS's event loop system is mainly used with graphical applications, and LibGUI and IPC are deeply integrated into it. If you are working on a command-line application, chances are you don't have to deal with the event loop, though that's not a universal rule.
|
LibCore's event loop system is mainly used with graphical applications, and LibGUI and IPC are deeply integrated into it. If you are working on a command-line application, chances are you don't have to deal with the event loop, though that's not a universal rule.
|
||||||
|
|
||||||
## How it works
|
## How it works
|
||||||
|
|
||||||
|
|
|
@ -4,23 +4,22 @@ Helix comes with support for `clangd` and `clang-format` out of the box! However
|
||||||
The following `.clangd` should be placed in the project root:
|
The following `.clangd` should be placed in the project root:
|
||||||
```yaml
|
```yaml
|
||||||
CompileFlags:
|
CompileFlags:
|
||||||
CompilationDatabase: Build/x86_64 # Or whatever architecture you're targeting, e.g. aarch64
|
CompilationDatabase: Build/lagom
|
||||||
Add: [-D__serenity__]
|
|
||||||
|
|
||||||
Diagnostics:
|
Diagnostics:
|
||||||
UnusedIncludes: None
|
UnusedIncludes: None
|
||||||
MissingIncludes: None
|
MissingIncludes: None
|
||||||
```
|
```
|
||||||
|
|
||||||
You also need to configure the clangd server to detect headers properly from the Serenity toolchain. To do this, create a `.helix/languages.toml` file in the project root:
|
You also need to configure the clangd server to not insert headers improperly. To do this, create a `.helix/languages.toml` file in the project root:
|
||||||
```toml
|
```toml
|
||||||
[language-server.serenity]
|
[language-server.ladybird]
|
||||||
command = "clangd"
|
command = "clangd"
|
||||||
args = ["--query-driver=/path/to/serenity/Toolchain/Local/**/*", "--header-insertion=never"]
|
args = ["--header-insertion=never"]
|
||||||
|
|
||||||
[[language]]
|
[[language]]
|
||||||
name = "cpp"
|
name = "cpp"
|
||||||
language-servers = ["serenity"]
|
language-servers = ["ladybird"]
|
||||||
```
|
```
|
||||||
|
|
||||||
> Make sure to replace `/path/to/serenity` with the actual path in the snippet above!
|
> Make sure to replace `/path/to/ladybird` with the actual path in the snippet above!
|
||||||
|
|
|
@ -4,7 +4,7 @@ NVim can be configured to use the [COC-clangd](https://github.com/clangd/coc-cla
|
||||||
plugin to provide code-completion as well as inline
|
plugin to provide code-completion as well as inline
|
||||||
[git blame](https://github.com/f-person/git-blame.nvim) using [vim-plug](https://github.com/junegunn/vim-plug).
|
[git blame](https://github.com/f-person/git-blame.nvim) using [vim-plug](https://github.com/junegunn/vim-plug).
|
||||||
|
|
||||||
Make sure you ran `Meta/serenity.sh run` at least once already.
|
Make sure you ran `Meta/ladybird.sh run ladybird` at least once already.
|
||||||
|
|
||||||
# Install vim-plug
|
# Install vim-plug
|
||||||
|
|
||||||
|
@ -46,7 +46,6 @@ system and customize the `inlayHints.sep` based on your preference.
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"clangd.fallbackFlags": ["-std=c++23"],
|
"clangd.fallbackFlags": ["-std=c++23"],
|
||||||
"clangd.arguments": ["--query-driver=${workspaceFolder}/Toolchain/Local/**/*"],
|
|
||||||
"semanticTokens.enable": true,
|
"semanticTokens.enable": true,
|
||||||
"inlayHint.subSeparator": "︴",
|
"inlayHint.subSeparator": "︴",
|
||||||
"inlayHints.enableParameter": true,
|
"inlayHints.enableParameter": true,
|
||||||
|
@ -179,12 +178,12 @@ nmap <silent>gs :CocCommand clangd.switchSourceHeader vsplit<CR>
|
||||||
# Configure .clangd
|
# Configure .clangd
|
||||||
|
|
||||||
> **Note**: Every time a new source is added or the compilation commands get adjusted
|
> **Note**: Every time a new source is added or the compilation commands get adjusted
|
||||||
(through CMake) you need to rerun `./Meta/serenity.sh rebuild`.
|
(through CMake) you need to rerun `./Meta/ladybird.sh rebuild`.
|
||||||
|
|
||||||
Link `ln -s /path/to/ladybird/Build/x86_64/compile_commands.json /path/to/ladybird/compile_commands.json`.
|
Link `ln -s /path/to/ladybird/Build/lagom/compile_commands.json /path/to/ladybird/compile_commands.json`.
|
||||||
|
|
||||||
Create `/path/to/ladybird/.clangd` (replace `/path/to/ladybird`
|
Create `/path/to/ladybird/.clangd` (replace `/path/to/ladybird`
|
||||||
with your SerenityOS directory) with content of the clangd section in the
|
with your ladybird directory) with content of the clangd section in the
|
||||||
[VSCodeConfiguration.md](./VSCodeConfiguration.md).
|
[VSCodeConfiguration.md](./VSCodeConfiguration.md).
|
||||||
|
|
||||||
> **Note**: You can add a `Remove` part, where you can remove unwanted flags
|
> **Note**: You can add a `Remove` part, where you can remove unwanted flags
|
||||||
|
|
|
@ -3,7 +3,7 @@
|
||||||
----
|
----
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
There are three main C++ smart pointer types used in SerenityOS. Each type describes the ownership (or lack thereof) of the pointee.
|
There are three main C++ smart pointer types used in Ladybird. Each type describes the ownership (or lack thereof) of the pointee.
|
||||||
|
|
||||||
The reason for using these pointers is to make it explicit through code who owns which resources, and how ownership is transferred. They also serve as a guard against memory leaks and use-after-free bugs.
|
The reason for using these pointers is to make it explicit through code who owns which resources, and how ownership is transferred. They also serve as a guard against memory leaks and use-after-free bugs.
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
# String Formatting
|
# String Formatting
|
||||||
|
|
||||||
Many places in Serenity allow you to format strings, similar to `printf()`, for example `ByteString::formatted()`
|
Many places in Ladybird allow you to format strings, similar to `printf()`, for example `ByteString::formatted()`
|
||||||
, `StringBuilder::appendff()`, or `dbgln()`. These are checked at compile time to ensure the format string matches the
|
, `StringBuilder::appendff()`, or `dbgln()`. These are checked at compile time to ensure the format string matches the
|
||||||
number of parameters. The syntax is largely based on
|
number of parameters. The syntax is largely based on
|
||||||
the [C++ `std::formatter` syntax](https://en.cppreference.com/w/cpp/utility/format/formatter#Standard_format_specification)
|
the [C++ `std::formatter` syntax](https://en.cppreference.com/w/cpp/utility/format/formatter#Standard_format_specification)
|
||||||
|
|
|
@ -6,36 +6,9 @@ In case of an error, you might find an answer of how to deal it here.
|
||||||
|
|
||||||
### CMake fails to configure the build because it's outdated
|
### CMake fails to configure the build because it's outdated
|
||||||
|
|
||||||
Ensure your CMake version is >= 3.16 with `cmake --version`. If your system doesn't provide a suitable
|
Ensure your CMake version is >= 3.25 with `cmake --version`. If your system doesn't provide a suitable
|
||||||
version of CMake, you can download a binary release from the [CMake website](https://cmake.org/download).
|
version of CMake, you can download a binary release from the [CMake website](https://cmake.org/download).
|
||||||
|
|
||||||
### The toolchain is outdated
|
|
||||||
|
|
||||||
We strive to use the latest compilers and build tools to ensure the best developer experience; so every
|
|
||||||
few months, the toolchain needs to be updated. When such an update is due, an error like the following
|
|
||||||
will be printed during the build:
|
|
||||||
|
|
||||||
```
|
|
||||||
CMake Error at CMakeLists.txt:28 (message):
|
|
||||||
GNU version (13.1.0) does not match expected compiler version (13.2.0).
|
|
||||||
|
|
||||||
Please rebuild the GNU Toolchain
|
|
||||||
```
|
|
||||||
|
|
||||||
Or like this one:
|
|
||||||
|
|
||||||
```
|
|
||||||
Your toolchain has an old version of binutils installed.
|
|
||||||
installed version: "GNU ld (GNU Binutils) 2.40"
|
|
||||||
expected version: "GNU ld (GNU Binutils) 2.41"
|
|
||||||
Please run Meta/serenity.sh rebuild-toolchain x86_64 to update it.
|
|
||||||
```
|
|
||||||
|
|
||||||
Run `Meta/serenity.sh rebuild-toolchain x86_64` to perform the update.
|
|
||||||
|
|
||||||
CMake might cache the compiler version in some cases and print an error even after the toolchain has been rebuilt.
|
|
||||||
If this happens, run `Meta/serenity.sh rebuild x86_64` to start over from a fresh build directory.
|
|
||||||
|
|
||||||
### GCC is missing or is outdated
|
### GCC is missing or is outdated
|
||||||
|
|
||||||
Ensure your gcc version is >= 13 with `gcc --version`. Otherwise, install it. If your gcc binary is not
|
Ensure your gcc version is >= 13 with `gcc --version`. Otherwise, install it. If your gcc binary is not
|
||||||
|
|
|
@ -1,8 +1,8 @@
|
||||||
# Visual Studio Code Project Configuration
|
# Visual Studio Code Project Configuration
|
||||||
|
|
||||||
Visual Studio Code requires some configuration files, and a tailored ``settings.json`` file to understand serenity.
|
Visual Studio Code requires some configuration files, and a tailored ``settings.json`` file to understand ladybird.
|
||||||
|
|
||||||
The WSL Remote extension allows you to use VS Code in Windows while using the normal WSL workflow. This works well, but for code comprehension speed you should put the Serenity directory on your WSL root partition.
|
The WSL Remote extension allows you to use VS Code in Windows while using the normal WSL workflow. This works well, but for code comprehension speed you should put the ladybird directory on your WSL root partition.
|
||||||
|
|
||||||
The recommended extensions for VS Code include:
|
The recommended extensions for VS Code include:
|
||||||
|
|
||||||
|
@ -17,13 +17,12 @@ Clangd has the best support for cross-compiling workflows, especially if configu
|
||||||
|
|
||||||
The official clangd extension can be used for C++ comprehension. It is recommended in general, as it is most likely to work on all platforms.
|
The official clangd extension can be used for C++ comprehension. It is recommended in general, as it is most likely to work on all platforms.
|
||||||
|
|
||||||
clangd uses ``compile_commands.json`` files to understand the project. CMake will generate these in either Build/x86_64, Build/x86_64clang, and Build/lagom.
|
clangd uses ``compile_commands.json`` files to understand the project. CMake will generate these in Build/lagom.
|
||||||
Depending on which configuration you use most, set the CompilationDatabase configuration item in the below ``.clangd`` file accordingly. It goes at the root of your checkout (``serenity/.clangd``):
|
Depending on which configuration you use most, set the CompilationDatabase configuration item in the below ``.clangd`` file accordingly. It goes at the root of your checkout (``ladybird/.clangd``):
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
CompileFlags:
|
CompileFlags:
|
||||||
Add: [-D__serenity__]
|
CompilationDatabase: Build/lagom
|
||||||
CompilationDatabase: Build/x86_64
|
|
||||||
|
|
||||||
Diagnostics:
|
Diagnostics:
|
||||||
UnusedIncludes: None
|
UnusedIncludes: None
|
||||||
|
@ -33,14 +32,10 @@ Diagnostics:
|
||||||
The UnusedIncludes and MissingIncludes flags are used to disable the [Include Cleaner](https://clangd.llvm.org/design/include-cleaner) feature of newer clangd releases.
|
The UnusedIncludes and MissingIncludes flags are used to disable the [Include Cleaner](https://clangd.llvm.org/design/include-cleaner) feature of newer clangd releases.
|
||||||
It can be re-enabled if you don't mind the noisy inlay hints and problems in the problem view.
|
It can be re-enabled if you don't mind the noisy inlay hints and problems in the problem view.
|
||||||
|
|
||||||
Run ``./Meta/serenity.sh run`` at least once to generate the ``compile_commands.json`` file.
|
Run ``./Meta/ladybird.sh run ladybird`` at least once to generate the ``compile_commands.json`` file.
|
||||||
|
|
||||||
In addition to the ``.clangd`` file, the ``settings.json`` file below has a required ``clangd.arguments`` entry for ``--query-driver`` that allows clangd to find the cross-compiler's built-in include paths.
|
|
||||||
|
|
||||||
#### Known issues
|
#### Known issues
|
||||||
|
|
||||||
- Some distribution clangd packages still have issues identifying paths to the serenity cross-compilers' builtin include paths after supplying the ``--query-driver`` option from ``settings.json``. This has been seen on at least Debian. If the inlay hints suggest that ``<new>`` cannot be found, first triple check your configuration matches the ``.clangd`` file from this section, verify that you've run the OS via ``Meta/serenity.sh run``, and quadruple check your ``clangd.arguments`` section in the project-local ``settings.json`` file. If all of the above are correct, building ``clangd`` from the serenity clang toolchain is known to work. See [AdvancedBuildInstructions](AdvancedBuildInstructions.md#serenity-aware-clang-tools) for steps on how to build it from source. After building from source, be sure to set ``clangd.path`` in your ``settings.json`` to ``${workspaceFolder}/Toolchain/Local/clang/bin/clangd``.
|
|
||||||
|
|
||||||
- clangd has a tendency to crash when stressing bleeding edge compiler features. You can usually just restart it via the command palette. If that doesn't help, close currently open C++ files and/or switch branches before restarting, which helps sometimes.
|
- clangd has a tendency to crash when stressing bleeding edge compiler features. You can usually just restart it via the command palette. If that doesn't help, close currently open C++ files and/or switch branches before restarting, which helps sometimes.
|
||||||
|
|
||||||
### DSL syntax highlighting
|
### DSL syntax highlighting
|
||||||
|
@ -51,8 +46,8 @@ serialization format (no extension) as output by js with the -d option.
|
||||||
|
|
||||||
### Microsoft C/C++ tools
|
### Microsoft C/C++ tools
|
||||||
|
|
||||||
This extension can be used as-is, but you need to point it to the custom Serenity compilers. Note that enabling the extension in the same workspace as the
|
Note that enabling the extension in the same workspace as the clangd and clang-format extensions will cause conflicts.
|
||||||
clangd and clang-format extensions will cause conflicts. If you choose to use Microsoft C/C++ Tools rather than clangd and clang-format, use the
|
If you choose to use Microsoft C/C++ Tools rather than clangd and clang-format, use the
|
||||||
following ``c_cpp_properties.json`` to circumvent some errors. Even with the configuration in place, the extension will likely still report errors related to types and methods not being found.
|
following ``c_cpp_properties.json`` to circumvent some errors. Even with the configuration in place, the extension will likely still report errors related to types and methods not being found.
|
||||||
|
|
||||||
<details>
|
<details>
|
||||||
|
@ -62,28 +57,24 @@ following ``c_cpp_properties.json`` to circumvent some errors. Even with the con
|
||||||
{
|
{
|
||||||
"configurations": [
|
"configurations": [
|
||||||
{
|
{
|
||||||
"name": "userland-x86_64-gcc",
|
"name": "ladybird-gcc",
|
||||||
"includePath": [
|
"includePath": [
|
||||||
"${workspaceFolder}",
|
"${workspaceFolder}",
|
||||||
"${workspaceFolder}/Build/x86_64/",
|
"${workspaceFolder}/Build/lagom/",
|
||||||
"${workspaceFolder}/Build/x86_64/Userland",
|
"${workspaceFolder}/Build/lagom/Userland",
|
||||||
"${workspaceFolder}/Build/x86_64/Userland/Libraries",
|
"${workspaceFolder}/Build/lagom/Userland/Libraries",
|
||||||
"${workspaceFolder}/Build/x86_64/Userland/Services",
|
"${workspaceFolder}/Build/lagom/Userland/Services",
|
||||||
"${workspaceFolder}/Build/x86_64/Root/usr/include/**",
|
|
||||||
"${workspaceFolder}/Userland",
|
"${workspaceFolder}/Userland",
|
||||||
"${workspaceFolder}/Userland/Libraries",
|
"${workspaceFolder}/Userland/Libraries",
|
||||||
"${workspaceFolder}/Userland/Services",
|
"${workspaceFolder}/Userland/Services"
|
||||||
"${workspaceFolder}/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/**"
|
|
||||||
],
|
],
|
||||||
"defines": [
|
"defines": [
|
||||||
"DEBUG",
|
"DEBUG"
|
||||||
"__serenity__"
|
|
||||||
],
|
],
|
||||||
"compilerPath": "${workspaceFolder}/Toolchain/Local/x86_64/bin/x86_64-pc-serenity-g++",
|
|
||||||
"cStandard": "c17",
|
"cStandard": "c17",
|
||||||
"cppStandard": "c++23",
|
"cppStandard": "c++23",
|
||||||
"intelliSenseMode": "linux-gcc-x86",
|
"intelliSenseMode": "linux-gcc-x86",
|
||||||
"compileCommands": "Build/x86_64/compile_commands.json",
|
"compileCommands": "Build/lagom/compile_commands.json",
|
||||||
"compilerArgs": [
|
"compilerArgs": [
|
||||||
"-Wall",
|
"-Wall",
|
||||||
"-Wextra",
|
"-Wextra",
|
||||||
|
@ -92,18 +83,16 @@ following ``c_cpp_properties.json`` to circumvent some errors. Even with the con
|
||||||
"browse": {
|
"browse": {
|
||||||
"path": [
|
"path": [
|
||||||
"${workspaceFolder}",
|
"${workspaceFolder}",
|
||||||
"${workspaceFolder}/Build/x86_64/",
|
"${workspaceFolder}/Build/lagom/",
|
||||||
"${workspaceFolder}/Build/x86_64/Userland",
|
"${workspaceFolder}/Build/lagom/Userland",
|
||||||
"${workspaceFolder}/Build/x86_64/Userland/Libraries",
|
"${workspaceFolder}/Build/lagom/Userland/Libraries",
|
||||||
"${workspaceFolder}/Build/x86_64/Userland/Services",
|
"${workspaceFolder}/Build/lagom/Userland/Services",
|
||||||
"${workspaceFolder}/Build/x86_64/Root/usr/include/**",
|
|
||||||
"${workspaceFolder}/Userland",
|
"${workspaceFolder}/Userland",
|
||||||
"${workspaceFolder}/Userland/Libraries",
|
"${workspaceFolder}/Userland/Libraries",
|
||||||
"${workspaceFolder}/Userland/Services",
|
"${workspaceFolder}/Userland/Services"
|
||||||
"${workspaceFolder}/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/**"
|
|
||||||
],
|
],
|
||||||
"limitSymbolsToIncludedHeaders": true,
|
"limitSymbolsToIncludedHeaders": true,
|
||||||
"databaseFilename": "${workspaceFolder}/Build/x86_64/"
|
"databaseFilename": "${workspaceFolder}/Build/lagom/"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
|
@ -129,7 +118,6 @@ These belong in the `.vscode/settings.json` of Serenity.
|
||||||
"Toolchain/Tarballs/**": true,
|
"Toolchain/Tarballs/**": true,
|
||||||
"Toolchain/Build/**": true,
|
"Toolchain/Build/**": true,
|
||||||
"Build/**": true,
|
"Build/**": true,
|
||||||
"build/**": true,
|
|
||||||
},
|
},
|
||||||
"search.exclude": {
|
"search.exclude": {
|
||||||
"**/.git": true,
|
"**/.git": true,
|
||||||
|
@ -137,7 +125,6 @@ These belong in the `.vscode/settings.json` of Serenity.
|
||||||
"Toolchain/Tarballs/**": true,
|
"Toolchain/Tarballs/**": true,
|
||||||
"Toolchain/Build/**": true,
|
"Toolchain/Build/**": true,
|
||||||
"Build/**": true,
|
"Build/**": true,
|
||||||
"build/**": true,
|
|
||||||
},
|
},
|
||||||
// Force clang-format to respect Serenity's .clang-format style file. This is not necessary if you're not using the Microsoft C++ extension.
|
// Force clang-format to respect Serenity's .clang-format style file. This is not necessary if you're not using the Microsoft C++ extension.
|
||||||
"C_Cpp.clang_format_style": "file",
|
"C_Cpp.clang_format_style": "file",
|
||||||
|
@ -150,9 +137,7 @@ These belong in the `.vscode/settings.json` of Serenity.
|
||||||
// git commit message length
|
// git commit message length
|
||||||
"git.inputValidationLength": 72,
|
"git.inputValidationLength": 72,
|
||||||
"git.inputValidationSubjectLength": 72,
|
"git.inputValidationSubjectLength": 72,
|
||||||
// Tell clangd to ask the cross-compilers for their builtin include paths
|
|
||||||
"clangd.arguments": [
|
"clangd.arguments": [
|
||||||
"--query-driver=${workspaceFolder}/Toolchain/Local/**/*",
|
|
||||||
"--header-insertion=never" // See https://github.com/clangd/clangd/issues/1247
|
"--header-insertion=never" // See https://github.com/clangd/clangd/issues/1247
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
@ -162,11 +147,9 @@ These belong in the `.vscode/settings.json` of Serenity.
|
||||||
|
|
||||||
### Custom Tasks
|
### Custom Tasks
|
||||||
|
|
||||||
You can create custom tasks (`.vscode/tasks.json`) to quickly compile Serenity.
|
You can create custom tasks (`.vscode/tasks.json`) to quickly compile Ladybird.
|
||||||
The following three example tasks should suffice in most situations, and allow you to specify the build system to use, as well as give you error highlighting.
|
The following three example tasks should suffice in most situations, and allow you to specify the build system to use, as well as give you error highlighting.
|
||||||
|
|
||||||
Note: The Assertion und KUBSan Problem matchers will only run after you have closed qemu.
|
|
||||||
|
|
||||||
<details>
|
<details>
|
||||||
<summary>.vscode/tasks.json</summary>
|
<summary>.vscode/tasks.json</summary>
|
||||||
|
|
||||||
|
@ -191,7 +174,7 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo
|
||||||
],
|
],
|
||||||
"args": [
|
"args": [
|
||||||
"-c",
|
"-c",
|
||||||
"\"Meta/serenity.sh build lagom\""
|
"\"Meta/ladybird.sh build\""
|
||||||
],
|
],
|
||||||
"presentation": {
|
"presentation": {
|
||||||
"echo": true,
|
"echo": true,
|
||||||
|
@ -209,23 +192,21 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo
|
||||||
"command": "bash",
|
"command": "bash",
|
||||||
"args": [
|
"args": [
|
||||||
"-c",
|
"-c",
|
||||||
"Meta/serenity.sh build ${input:arch} ${input:compiler}"
|
"Meta/ladybird.sh build"
|
||||||
],
|
],
|
||||||
"problemMatcher": [
|
"problemMatcher": [
|
||||||
{
|
{
|
||||||
"base": "$gcc",
|
"base": "$gcc",
|
||||||
"fileLocation": [
|
"fileLocation": [
|
||||||
"relative",
|
"relative",
|
||||||
// FIXME: Clang uses ${input:arch}clang
|
"${workspaceFolder}/Build/lagom"
|
||||||
"${workspaceFolder}/Build/${input:arch}"
|
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"source": "gcc",
|
"source": "gcc",
|
||||||
"fileLocation": [
|
"fileLocation": [
|
||||||
"relative",
|
"relative",
|
||||||
// FIXME: Clang uses ${input:arch}clang
|
"${workspaceFolder}/Build/lagom"
|
||||||
"${workspaceFolder}/Build/${input:arch}"
|
|
||||||
],
|
],
|
||||||
"pattern": [
|
"pattern": [
|
||||||
{
|
{
|
||||||
|
@ -248,11 +229,11 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo
|
||||||
"command": "bash",
|
"command": "bash",
|
||||||
"args": [
|
"args": [
|
||||||
"-c",
|
"-c",
|
||||||
"Meta/serenity.sh run ${input:arch} ${input:compiler}"
|
"Meta/ladybird.sh run ladybird"
|
||||||
],
|
],
|
||||||
"options": {
|
"options": {
|
||||||
"env": {
|
"env": {
|
||||||
// Put your custom run configuration here, e.g. SERENITY_RAM_SIZE
|
// Put your custom run configuration here
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
"problemMatcher": [
|
"problemMatcher": [
|
||||||
|
@ -260,16 +241,14 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo
|
||||||
"base": "$gcc",
|
"base": "$gcc",
|
||||||
"fileLocation": [
|
"fileLocation": [
|
||||||
"relative",
|
"relative",
|
||||||
// FIXME: Clang uses ${input:arch}clang
|
"${workspaceFolder}/Build/lagom"
|
||||||
"${workspaceFolder}/Build/${input:arch}"
|
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"source": "gcc",
|
"source": "gcc",
|
||||||
"fileLocation": [
|
"fileLocation": [
|
||||||
"relative",
|
"relative",
|
||||||
// FIXME: Clang uses ${input:arch}clang
|
"${workspaceFolder}/Build/lagom"
|
||||||
"${workspaceFolder}/Build/${input:arch}"
|
|
||||||
],
|
],
|
||||||
"pattern": [
|
"pattern": [
|
||||||
{
|
{
|
||||||
|
@ -280,26 +259,6 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
{
|
|
||||||
"source": "KUBSan",
|
|
||||||
"owner": "cpp",
|
|
||||||
"fileLocation": [
|
|
||||||
"relative",
|
|
||||||
"${workspaceFolder}"
|
|
||||||
],
|
|
||||||
"pattern": [
|
|
||||||
{
|
|
||||||
"regexp": "KUBSAN: (.*)",
|
|
||||||
"message": 0
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"regexp": "KUBSAN: at ../(.*), line (\\d*), column: (\\d*)",
|
|
||||||
"file": 1,
|
|
||||||
"line": 2,
|
|
||||||
"column": 3
|
|
||||||
}
|
|
||||||
]
|
|
||||||
},
|
|
||||||
{
|
{
|
||||||
"source": "Assertion Failed",
|
"source": "Assertion Failed",
|
||||||
"owner": "cpp",
|
"owner": "cpp",
|
||||||
|
@ -316,34 +275,11 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo
|
||||||
],
|
],
|
||||||
"fileLocation": [
|
"fileLocation": [
|
||||||
"relative",
|
"relative",
|
||||||
// FIXME: Clang uses ${input:arch}clang
|
"${workspaceFolder}/Build/lagom"
|
||||||
"${workspaceFolder}/Build/${input:arch}"
|
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
],
|
|
||||||
"inputs": [
|
|
||||||
{
|
|
||||||
"id": "compiler",
|
|
||||||
"description": "Compiler to use",
|
|
||||||
"type": "pickString",
|
|
||||||
"default": "GNU",
|
|
||||||
"options": [
|
|
||||||
"GNU",
|
|
||||||
"Clang"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": "arch",
|
|
||||||
"description": "Architecture to compile for",
|
|
||||||
"type": "pickString",
|
|
||||||
"default": "x86_64",
|
|
||||||
"options": [
|
|
||||||
"x86_64",
|
|
||||||
"aarch64"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
@ -352,7 +288,7 @@ Note: The Assertion und KUBSan Problem matchers will only run after you have clo
|
||||||
|
|
||||||
### License snippet
|
### License snippet
|
||||||
|
|
||||||
The following snippet may be useful if you want to quickly generate a license header, put it in `.vscode/serenity.code-snippets`:
|
The following snippet may be useful if you want to quickly generate a license header, put it in `.vscode/ladybird.code-snippets`:
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"License": {
|
"License": {
|
||||||
|
|
|
@ -4,9 +4,9 @@ Vim can be configured to use the [YouCompleteMe](https://github.com/ycm-core/You
|
||||||
plugin to provide code-completion.
|
plugin to provide code-completion.
|
||||||
|
|
||||||
Once you've installed the YouCompleteMe plugin you should whitelist the
|
Once you've installed the YouCompleteMe plugin you should whitelist the
|
||||||
configuration file that is part of the SerenityOS repository. You can
|
configuration file that is part of the ladybird repository. You can
|
||||||
do this by adding the following option to your `.vimrc` file:
|
do this by adding the following option to your `.vimrc` file:
|
||||||
|
|
||||||
```vim
|
```vim
|
||||||
let g:ycm_extra_conf_globlist = ['~/serenity/.ycm_extra_conf.py']
|
let g:ycm_extra_conf_globlist = ['~/ladybird/.ycm_extra_conf.py']
|
||||||
```
|
```
|
||||||
|
|
|
@ -54,7 +54,7 @@ endif()
|
||||||
# FIXME: BUILD_SHARED_LIBS has a default of OFF, as it's intended to be set by the
|
# FIXME: BUILD_SHARED_LIBS has a default of OFF, as it's intended to be set by the
|
||||||
# user when configuring the project. We should instead change libjs-test262
|
# user when configuring the project. We should instead change libjs-test262
|
||||||
# and oss-fuzz to set this option on their end, and enable it by default in
|
# and oss-fuzz to set this option on their end, and enable it by default in
|
||||||
# Meta/serenity.sh. This is #9867.
|
# Meta/ladybird.sh. This is #9867.
|
||||||
option(BUILD_SHARED_LIBS "Build shared libraries instead of static libraries" ON)
|
option(BUILD_SHARED_LIBS "Build shared libraries instead of static libraries" ON)
|
||||||
|
|
||||||
find_package(Threads REQUIRED)
|
find_package(Threads REQUIRED)
|
||||||
|
|
|
@ -12,7 +12,7 @@ if [ -z "${MARKDOWN_CHECK_BINARY:-}" ] ; then
|
||||||
fi
|
fi
|
||||||
if ! [ -r Build/lagom/bin/markdown-check ] ; then
|
if ! [ -r Build/lagom/bin/markdown-check ] ; then
|
||||||
echo "Lagom executable markdown-check was not built. Skipping markdown check."
|
echo "Lagom executable markdown-check was not built. Skipping markdown check."
|
||||||
echo "To enable this check, you may need to run './Meta/serenity.sh build lagom' first."
|
echo "To enable this check, you may need to run './Meta/ladybird.sh build' first."
|
||||||
exit 0
|
exit 0
|
||||||
fi
|
fi
|
||||||
MARKDOWN_CHECK_BINARY="Build/lagom/bin/markdown-check"
|
MARKDOWN_CHECK_BINARY="Build/lagom/bin/markdown-check"
|
||||||
|
|
Loading…
Reference in a new issue