2022-10-04 17:45:47 +03:00
# Ladybird browser build instructions
## Build Prerequisites
2024-05-17 16:40:40 +03:00
Qt6 development packages and a C++23 capable compiler are required. g++-13 or clang-17 are required at a minimum for c++23 support.
2023-02-03 14:58:48 +03:00
2023-11-02 20:53:38 +03:00
NOTE: In all of the below lists of packages, the Qt6 multimedia package is not needed if your Linux system supports PulseAudio.
2023-02-03 14:58:48 +03:00
On Debian/Ubuntu required packages include, but are not limited to:
2022-10-04 17:45:47 +03:00
```
2024-06-20 02:01:41 +03:00
sudo apt install autoconf autoconf-archive automake build-essential cmake libavcodec-dev libgl1-mesa-dev ninja-build qt6-base-dev qt6-tools-dev-tools qt6-multimedia-dev ccache fonts-liberation2 zip unzip curl tar
2022-10-04 17:45:47 +03:00
```
2023-02-03 14:58:48 +03:00
For Ubuntu 20.04 and above, ensure that the Qt6 Wayland packages are available:
```
sudo apt install qt6-wayland
```
2022-10-04 17:45:47 +03:00
On Arch Linux/Manjaro:
```
2024-06-20 02:01:41 +03:00
sudo pacman -S --needed base-devel cmake ffmpeg libgl ninja qt6-base qt6-tools qt6-wayland qt6-multimedia ccache ttf-liberation curl unzip zip tar autoconf-archive
2022-10-04 17:45:47 +03:00
```
On Fedora or derivatives:
```
2024-06-10 03:28:19 +03:00
sudo dnf install cmake libglvnd-devel ninja-build qt6-qtbase-devel qt6-qttools-devel qt6-qtwayland-devel qt6-qtmultimedia-devel ccache liberation-sans-fonts curl zip unzip tar autoconf-archive
2022-10-04 17:45:47 +03:00
```
2023-04-27 21:26:17 +03:00
On openSUSE:
```
2024-06-07 00:54:59 +03:00
sudo zypper install cmake libglvnd-devel ninja qt6-base-devel qt6-multimedia-devel qt6-tools-devel qt6-wayland-devel ccache liberation-fonts curl zip unzip tar
2023-04-27 21:26:17 +03:00
```
2024-03-16 11:36:09 +03:00
On NixOS or with Nix:
```console
nix develop .#ladybird
2023-12-04 04:13:55 +03:00
# With a custom entrypoint, for example your favorite shell
2024-03-16 11:36:09 +03:00
nix develop .#ladybird --command bash
2022-09-22 14:22:28 +03:00
```
2023-12-04 04:13:55 +03:00
2024-03-16 11:36:09 +03:00
On NixOS or with Nix using your host `nixpkgs` and the legacy `nix-shell` tool:
```console
nix-shell Ladybird
2023-12-04 04:13:55 +03:00
# With a custom entrypoint, for example your favorite shell
2024-03-16 11:36:09 +03:00
nix-shell --command bash Ladybird
2023-09-01 17:30:49 +03:00
```
2022-09-22 14:22:28 +03:00
2022-10-04 17:45:47 +03:00
On macOS:
2024-04-30 16:19:35 +03:00
Xcode 14 versions before 14.3 might crash while building ladybird. Xcode 14.3 or clang from homebrew may be required to successfully build ladybird.
2023-02-03 14:58:48 +03:00
2022-10-04 17:45:47 +03:00
```
xcode-select --install
2024-06-20 02:01:41 +03:00
brew install autoconf autoconf-archive automake cmake ffmpeg ninja ccache pkg-config
2023-10-24 17:35:33 +03:00
```
If you also plan to use the Qt chrome on macOS:
```
brew install qt
2022-10-04 17:45:47 +03:00
```
2023-02-28 12:32:56 +03:00
On OpenIndiana:
2023-05-06 17:28:34 +03:00
Note that OpenIndiana's latest GCC port (GCC 11) is too old to build Ladybird, so you need Clang, which is available in the repository.
2023-02-28 12:32:56 +03:00
```
2024-05-10 18:15:57 +03:00
pfexec pkg install cmake ninja clang-17 libglvnd qt6
2023-02-28 12:32:56 +03:00
```
2023-08-29 18:13:46 +03:00
On Haiku:
```
pkgman install cmake ninja cmd:python3 qt6_base_devel qt6_multimedia_devel qt6_tools_devel openal_devel
```
2023-02-03 14:58:48 +03:00
On Windows:
2022-10-04 17:45:47 +03:00
2023-02-03 14:58:48 +03:00
WSL2/WSLg are preferred, as they provide a linux environment that matches one of the above distributions.
MinGW/MSYS2 are not supported, but may work with sufficient elbow grease. Native Windows builds are not supported with either clang-cl or MSVC.
2023-09-15 00:59:33 +03:00
For Android:
On a Unix-like platform, install the prerequisites for that platform and then see the [Android Studio guide ](AndroidStudioConfiguration.md ).
2023-10-24 17:35:33 +03:00
Or, download a version of Gradle >= 8.0.0, and run the ``gradlew`` program in ``Ladybird/Android``
2023-09-15 00:59:33 +03:00
2023-02-03 14:58:48 +03:00
## Build steps
2024-06-01 02:27:20 +03:00
### Using ladybird.sh
2023-02-03 14:58:48 +03:00
2024-06-01 02:27:20 +03:00
The simplest way to build and run ladybird is via the ladybird.sh script:
2022-10-04 17:45:47 +03:00
2023-08-25 14:05:57 +03:00
```bash
2024-05-31 00:06:21 +03:00
# From /path/to/ladybird
2024-06-01 02:27:20 +03:00
./Meta/ladybird.sh run ladybird
./Meta/ladybird.sh gdb ladybird
2022-10-04 17:45:47 +03:00
```
2023-10-24 17:35:33 +03:00
The above commands will build Ladybird with one of the following browser chromes, depending on the platform:
* [Android UI ](https://developer.android.com/develop/ui ) - The native chrome on Android.
2023-08-25 14:05:57 +03:00
* [AppKit ](https://developer.apple.com/documentation/appkit?language=objc ) - The native chrome on macOS.
2023-10-24 17:35:33 +03:00
* [Qt ](https://doc.qt.io/qt-6/ ) - The chrome used on all other platforms.
2023-08-25 14:05:57 +03:00
2023-10-24 17:35:33 +03:00
The Qt chrome is available on platforms where it is not the default as well (except on Android). To build the
Qt chrome, install the Qt dependencies for your platform, and enable the Qt chrome via CMake:
2023-08-25 14:05:57 +03:00
```bash
2024-05-31 00:06:21 +03:00
# From /path/to/ladybird
2024-06-05 00:10:48 +03:00
cmake --preset default -DENABLE_QT=ON
2023-08-25 14:05:57 +03:00
```
2023-10-24 17:35:33 +03:00
To re-disable the Qt chrome, run the above command with `-DENABLE_QT=OFF` .
2023-02-03 14:58:48 +03:00
### Resource files
2024-05-31 00:06:21 +03:00
Ladybird requires resource files from the ladybird/Base/res directory in order to properly load
2024-06-05 00:10:48 +03:00
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.
2023-02-03 14:58:48 +03:00
### Custom CMake build directory
2024-06-05 00:10:48 +03:00
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.
2023-02-03 14:58:48 +03:00
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``.
2024-06-01 02:27:20 +03:00
Note that when using a custom build directory rather than Meta/ladybird.sh, the user may need to provide
2024-05-17 16:40:40 +03:00
a suitable C++ compiler (g++ >= 13, clang >= 14, Apple Clang >= 14.3) via the CMAKE_CXX_COMPILER and
2023-02-03 14:58:48 +03:00
CMAKE_C_COMPILER cmake options.
2022-10-04 17:45:47 +03:00
```
2024-06-05 00:10:48 +03:00
cmake -GNinja -B MyBuildDir
2023-02-03 14:58:48 +03:00
# optionally, add -DCMAKE_CXX_COMPILER=<suitable compiler> -DCMAKE_C_COMPILER=<matching c compiler>
2024-06-05 00:10:48 +03:00
cmake --build MyBuildDir
ninja -C MyBuildDir run-ladybird
2022-10-04 17:45:47 +03:00
```
2024-06-05 00:10:48 +03:00
### 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:
2022-12-24 02:47:02 +03:00
To automatically run in gdb:
```
2024-06-05 00:10:48 +03:00
ninja -C Build/ladybird debug-ladybird
2022-12-24 02:47:02 +03:00
```
2022-10-04 17:45:47 +03:00
2023-11-17 19:20:47 +03:00
To run without ninja rule on non-macOS systems:
2022-10-04 17:45:47 +03:00
```
2023-11-17 19:20:47 +03:00
./Build/ladybird/bin/Ladybird
```
To run without ninja rule on macOS:
```
open -W --stdout $(tty) --stderr $(tty) ./Build/ladybird/bin/Ladybird.app
# Or to launch with arguments:
open -W --stdout $(tty) --stderr $(tty) ./Build/ladybird/bin/Ladybird.app --args https://ladybird.dev
2022-10-04 17:45:47 +03:00
```
2024-04-08 22:15:00 +03:00
### Experimental GN build
There is an experimental GN build for Ladybird. It is not officially supported, but it is kept up to date on a best-effort
basis by interested contributors. See the [GN build instructions ](../Meta/gn/README.md ) for more information.
In general, the GN build organizes ninja rules in a more compact way than the CMake build, and it may be faster on some systems.
GN also allows building host and cross-targets in the same build directory, which is useful for managing dependencies on host tools when
cross-compiling to other platforms.
2023-07-06 13:42:24 +03:00
### Debugging with CLion
2024-06-05 00:10:48 +03:00
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.
2023-07-06 13:42:24 +03:00
2024-06-05 00:10:48 +03:00
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.
2023-07-06 13:42:24 +03:00
Now breakpoints, stepping and variable inspection will work.
2023-03-26 19:13:07 +03:00
### Debugging with Xcode on macOS
2024-06-01 02:27:20 +03:00
The `ladybird.sh` build script does not know how to generate Xcode projects, so creating the project must be done manually.
2023-03-26 19:13:07 +03:00
```
2024-06-04 00:46:00 +03:00
cmake -GXcode -B Build/ladybird
2023-03-26 19:13:07 +03:00
```
2023-05-06 17:28:34 +03:00
After generating an Xcode project into the specified build directory, you can open `ladybird.xcodeproj` in Xcode. The project has a ton of targets, many of which are generated code.
2023-03-26 19:13:07 +03:00
The only target that needs a scheme is the ladybird app bundle.
2023-02-28 12:32:56 +03:00
### Building on OpenIndiana
OpenIndiana needs some extra environment variables set to make sure it finds all the executables
and directories it needs for the build to work. The cmake files are in a non-standard path that
contains the Qt version (replace 6.2 with the Qt version you have installed) and you need to tell
it to use clang and clang++, or it will use gcc and g++ from GCC 10 which is currently the default
to build packages on OpenIndiana.
When running Ladybird, make sure that XDG_RUNTIME_DIR is set, or it will immediately crash as it
doesn't find a writable directory for its sockets.
```
2024-06-04 00:46:00 +03:00
CMAKE_PREFIX_PATH=/usr/lib/qt/6.2/lib/amd64/cmake cmake -GNinja -B Build/ladybird -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
2023-02-28 12:32:56 +03:00
cmake --build Build/ladybird
XDG_RUNTIME_DIR=/var/tmp ninja -C Build/ladybird run
```