Skip to content

Commit 2451a44

Browse files
awesomeklingADKaster
awesomekling
authored and
ADKaster
committed
Ladybird/Meta: Split out build instructions to a separate document
1 parent acec343 commit 2451a44

File tree

2 files changed

+155
-148
lines changed

2 files changed

+155
-148
lines changed

‎Ladybird/Documentation/BuildInstructions.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Ladybird browser build instructions
2+
3+
## Build Prerequisites
4+
5+
Qt6 development packages and a C++20 capable compiler are required. On Debian/Ubuntu required packages include, but are not limited to:
6+
7+
```
8+
sudo apt install build-essential cmake libgl1-mesa-dev ninja-build qt6-base-dev qt6-tools-dev-tools
9+
```
10+
11+
On Arch Linux/Manjaro:
12+
13+
```
14+
sudo pacman -S --needed base-devel cmake libgl ninja qt6-base qt6-tools qt6-wayland
15+
```
16+
17+
On Fedora or derivatives:
18+
```
19+
sudo dnf install cmake libglvnd-devel ninja-build qt6-qtbase-devel qt6-qttools-devel qt6-qtwayland-devel
20+
```
21+
22+
On macOS:
23+
24+
```
25+
xcode-select --install
26+
brew install qt ninja
27+
```
28+
29+
For the c++ compiler, gcc-11 or clang-13 are required at a minimum for c++20 support.
30+
31+
For Ubuntu 20.04 and above, ensure that the Qt6 Wayland packages are available:
32+
33+
```
34+
sudo apt install qt6-wayland
35+
```
36+
37+
38+
## Build steps
39+
40+
Basic workflow, using serenity source dir cloned from github:
41+
42+
```
43+
cmake -GNinja -B Build
44+
cmake --build Build
45+
ninja -C Build run
46+
```
47+
48+
Advanced workflow, using pre-existing serenity checkout.
49+
50+
If you previously didn't set SERENITY_SOURCE_DIR, probably want to blast the Build directory before doing this:
51+
52+
```
53+
cmake -GNinja -B Build -DSERENITY_SOURCE_DIR=/path/to/serenity
54+
ninja -C Build run
55+
```
56+
57+
To automatically run in gdb:
58+
```
59+
ninja -C Build debug
60+
```
61+
62+
To run without ninja rule:
63+
```
64+
# or your existing serenity checkout /path/to/serenity
65+
export SERENITY_SOURCE_DIR=${PWD}/Build/serenity
66+
./Build/ladybird # or, in macOS: open ./Build/ladybird.app
67+
```
68+
69+
## Experimental Android Build Steps
70+
71+
### Prepping Qt Creator
72+
73+
In order to build an Android APK, the following additional dependencies are required/recommended:
74+
75+
* Qt Creator 6.4.0 (dev branch)
76+
* Android Studio 2021.2 (dev branch)
77+
78+
Note that Qt Creator 6.3.x LTS does NOT have the required fix to [QTBUG-104580](https://bugreports.qt.io/browse/QTBUG-104580) as of 2022-07-16 in order to use NDK 24.
79+
80+
The build configuration was tested with the following packages from the Android SDK:
81+
82+
* Android Platform and Build Tools version 33
83+
* Android System Images for API 33 aka ``"system-images;android-33;google-apis;x86_64"``
84+
* Android NDK 24.0.8215888 for the llvm-14 based toolchain
85+
86+
In order to build ladybird for cross compilation, a separate serenity checkout is recommended.
87+
88+
e.g.
89+
```
90+
cd ~/Repos
91+
git clone https://github.com/SerenityOS/serenity
92+
```
93+
94+
First create a LagomTools build:
95+
96+
```
97+
cmake -GNinja -S /path/to/serenity -B BuildTools -Dpackage=LagomTools -DCMAKE_INSTALL_PREFIX=tool-install
98+
ninja -C BuildTools install
99+
```
100+
101+
Next, create a build configuration in Qt Creator that uses an ``Android Qt 6.4.0 Debug x86_64`` Kit by following the instructions [here](https://doc.qt.io/qt-6/android-getting-started.html).
102+
103+
Ensure that you get Android API 30 or higher, and Android NDK 24 or higher. In the initial standup, an API 33 SDK for Android 13 was used.
104+
105+
Setup Android device settings in Qt Creator following this [link](https://doc.qt.io/qtcreator/creator-developing-android.html). Note that Qt Creator might not like the Android NDK version 24 we downloaded earlier, as it's "too new" and "not supported". No worries, we can force it to like our version by editing the ``sdk_defintions.json`` file as described under [Viewing Android Tool Chain Settings](https://doc.qt.io/qtcreator/creator-developing-android.html#viewing-android-tool-chain-settings).
106+
107+
The relevant snippets of that JSON file are reproduced below. Just have to make sure it's happy with "platforms;android-33" and the exact installed NDK version.
108+
109+
```json
110+
"sdk_essential_packages": {
111+
"default": ["platform-tools", "platforms;android-33", "cmdline-tools;latest"],
112+
"linux": [],
113+
"mac": [],
114+
"windows": ["extras;google;usb_driver"]
115+
}
116+
},
117+
"specific_qt_versions": [
118+
{
119+
"versions": ["default"],
120+
"sdk_essential_packages": ["build-tools;33.0.0", "ndk;24.0.8215888"],
121+
"ndk_path": "ndk/24.0.8215888"
122+
},
123+
```
124+
125+
126+
### Building Ladybird for Android
127+
128+
Next, we can select the ``Android Qt 6.4.0 Debug x86_64`` Kit under the Projects tab of the Qt Creator, and watch CMake have a bad time because we need to edit the configuration.
129+
130+
In the ``Initial Configuration`` Tab of the CMake configuration for the Kit, edit the following initial values:
131+
132+
* ANDROID_NATIVE_API_LEVEL: 23 --> 30
133+
* LagomTools_DIR: New Directory setting, set to `/path/to/ladybird/tool-install/share/Lagom` for the LagomTools build we created earlier
134+
* SERENITY_SOURCE_DIR: New path setting, set to your local serenity checkout
135+
136+
Make sure to click the ``Reconfigure With Initial Parameters`` button, and triple check you've been editing the ``Initial Configuration`` tab and not the ``Current Configuration`` one.
137+
138+
Build the project, and cross your fingers that it all works :)
139+
140+
### Running the Android APK
141+
142+
In order to run the ladybird application, first make sure that the Debug settings in the bottom left of the Qt Creator window are trying to debug ladybird, and not another Lagom target, like LibArchive.
143+
144+
Create an Android device to test using the Tools->Options->Devices->Devices add button. This will only work for an Android device if the ``"system-images;android-33;google-apis;x86_64"`` or similar package is installed with the Android SDK ``sdkmanager`` tool.
145+
146+
Open up Android Studio, and in the Device Manager edit the created AVD to update its Internal Storage under Advanced Settings. Make sure it's at least 1 GiB. The default of 800 MiB is generally too small to install ladybird.
147+
148+
Hit the Debug or Run green arrows and hope for the best!
149+
150+
With luck the application should start up, install the required resources into the internal storage from the APK, and open up the default webpage. Clicking the home button to load serenityos.org should work.

‎Ladybird/README.md

Lines changed: 5 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,152 +1,9 @@
1-
# Ladybird Web Browser
1+
# Ladybird
22

3-
The Ladybird Web Browser is a browser using the [SerenityOS LibWeb](https://github.com/SerenityOS/serenity/tree/master/Userland/Libraries/LibWeb) engine with a Qt GUI.
3+
Ladybird is a web browser built on the [LibWeb](https://github.com/SerenityOS/serenity/tree/master/Userland/Libraries/LibWeb) and [LibJS](https://github.com/SerenityOS/serenity/tree/master/Userland/Libraries/LibJS) engines from [SerenityOS](https://github.com/SerenityOS/serenity) with a cross-platform GUI in Qt.
44

5-
## Build Prerequisites
5+
This is part of the greater SerenityOS project, and the separate repository may eventually be integrated in the [serenity](https://github.com/SerenityOS/serenity) monorepo.
66

7-
Qt6 development packages and a c++20-enabled compiler are required. On Debian/Ubuntu required packages include, but are not limited to:
7+
For more information about Ladybird, see [this blog post](https://awesomekling.github.io/Ladybird-a-new-cross-platform-browser-project/).
88

9-
```
10-
sudo apt install build-essential cmake libgl1-mesa-dev ninja-build qt6-base-dev qt6-tools-dev-tools
11-
```
12-
13-
On Arch Linux/Manjaro:
14-
15-
```
16-
sudo pacman -S --needed base-devel cmake libgl ninja qt6-base qt6-tools qt6-wayland
17-
```
18-
19-
On Fedora or derivatives:
20-
```
21-
sudo dnf install cmake libglvnd-devel ninja-build qt6-qtbase-devel qt6-qttools-devel qt6-qtwayland-devel
22-
```
23-
24-
On macOS:
25-
26-
```
27-
xcode-select --install
28-
brew install qt ninja
29-
```
30-
31-
For the c++ compiler, gcc-11 or clang-13 are required at a minimum for c++20 support.
32-
33-
For Ubuntu 20.04 and above, ensure that the Qt6 Wayland packages are available:
34-
35-
```
36-
sudo apt install qt6-wayland
37-
```
38-
39-
40-
## Build steps
41-
42-
Basic workflow, using serenity source dir cloned from github:
43-
44-
```
45-
cmake -GNinja -B Build
46-
cmake --build Build
47-
ninja -C Build run
48-
```
49-
50-
Advanced workflow, using pre-existing serenity checkout.
51-
52-
If you previously didn't set SERENITY_SOURCE_DIR, probably want to blast the Build directory before doing this:
53-
54-
```
55-
cmake -GNinja -B Build -DSERENITY_SOURCE_DIR=/path/to/serenity
56-
ninja -C Build run
57-
```
58-
59-
To automatically run in gdb:
60-
```
61-
ninja -C Build debug
62-
```
63-
64-
To run without ninja rule:
65-
```
66-
# or your existing serenity checkout /path/to/serenity
67-
export SERENITY_SOURCE_DIR=${PWD}/Build/serenity
68-
./Build/ladybird # or, in macOS: open ./Build/ladybird.app
69-
```
70-
71-
## Experimental Android Build Steps
72-
73-
### Prepping Qt Creator
74-
75-
In order to build an Android APK, the following additional dependencies are required/recommended:
76-
77-
* Qt Creator 6.4.0 (dev branch)
78-
* Android Studio 2021.2 (dev branch)
79-
80-
Note that Qt Creator 6.3.x LTS does NOT have the required fix to [QTBUG-104580](https://bugreports.qt.io/browse/QTBUG-104580) as of 2022-07-16 in order to use NDK 24.
81-
82-
The build configuration was tested with the following packages from the Android SDK:
83-
84-
* Android Platform and Build Tools version 33
85-
* Android System Images for API 33 aka ``"system-images;android-33;google-apis;x86_64"``
86-
* Android NDK 24.0.8215888 for the llvm-14 based toolchain
87-
88-
In order to build ladybird for cross compilation, a separate serenity checkout is recommended.
89-
90-
e.g.
91-
```
92-
cd ~/Repos
93-
git clone https://github.com/SerenityOS/serenity
94-
```
95-
96-
First create a LagomTools build:
97-
98-
```
99-
cmake -GNinja -S /path/to/serenity -B BuildTools -Dpackage=LagomTools -DCMAKE_INSTALL_PREFIX=tool-install
100-
ninja -C BuildTools install
101-
```
102-
103-
Next, create a build configuration in Qt Creator that uses an ``Android Qt 6.4.0 Debug x86_64`` Kit by following the instructions [here](https://doc.qt.io/qt-6/android-getting-started.html).
104-
105-
Ensure that you get Android API 30 or higher, and Android NDK 24 or higher. In the initial standup, an API 33 SDK for Android 13 was used.
106-
107-
Setup Android device settings in Qt Creator following this [link](https://doc.qt.io/qtcreator/creator-developing-android.html). Note that Qt Creator might not like the Android NDK version 24 we downloaded earlier, as it's "too new" and "not supported". No worries, we can force it to like our version by editing the ``sdk_defintions.json`` file as described under [Viewing Android Tool Chain Settings](https://doc.qt.io/qtcreator/creator-developing-android.html#viewing-android-tool-chain-settings).
108-
109-
The relevant snippets of that JSON file are reproduced below. Just have to make sure it's happy with "platforms;android-33" and the exact installed NDK version.
110-
111-
```json
112-
"sdk_essential_packages": {
113-
"default": ["platform-tools", "platforms;android-33", "cmdline-tools;latest"],
114-
"linux": [],
115-
"mac": [],
116-
"windows": ["extras;google;usb_driver"]
117-
}
118-
},
119-
"specific_qt_versions": [
120-
{
121-
"versions": ["default"],
122-
"sdk_essential_packages": ["build-tools;33.0.0", "ndk;24.0.8215888"],
123-
"ndk_path": "ndk/24.0.8215888"
124-
},
125-
```
126-
127-
128-
### Building Ladybird for Android
129-
130-
Next, we can select the ``Android Qt 6.4.0 Debug x86_64`` Kit under the Projects tab of the Qt Creator, and watch CMake have a bad time because we need to edit the configuration.
131-
132-
In the ``Initial Configuration`` Tab of the CMake configuration for the Kit, edit the following initial values:
133-
134-
* ANDROID_NATIVE_API_LEVEL: 23 --> 30
135-
* LagomTools_DIR: New Directory setting, set to `/path/to/ladybird/tool-install/share/Lagom` for the LagomTools build we created earlier
136-
* SERENITY_SOURCE_DIR: New path setting, set to your local serenity checkout
137-
138-
Make sure to click the ``Reconfigure With Initial Parameters`` button, and triple check you've been editing the ``Initial Configuration`` tab and not the ``Current Configuration`` one.
139-
140-
Build the project, and cross your fingers that it all works :)
141-
142-
### Running the Android APK
143-
144-
In order to run the ladybird application, first make sure that the Debug settings in the bottom left of the Qt Creator window are trying to debug ladybird, and not another Lagom target, like LibArchive.
145-
146-
Create an Android device to test using the Tools->Options->Devices->Devices add button. This will only work for an Android device if the ``"system-images;android-33;google-apis;x86_64"`` or similar package is installed with the Android SDK ``sdkmanager`` tool.
147-
148-
Open up Android Studio, and in the Device Manager edit the created AVD to update its Internal Storage under Advanced Settings. Make sure it's at least 1 GiB. The default of 800 MiB is generally too small to install ladybird.
149-
150-
Hit the Debug or Run green arrows and hope for the best!
151-
152-
With luck the application should start up, install the required resources into the internal storage from the APK, and open up the default webpage. Clicking the home button to load serenityos.org should work.
9+
See [build instructions](Documentation/BuildInstructions.md).

0 commit comments

Comments
 (0)