Meta: Update Documentation and CI for repo move

This commit is contained in:
Andrew Kaster 2024-05-30 15:06:21 -06:00 committed by Andreas Kling
parent dd1fbd3513
commit 6d3a54e4a8
Notes: sideshowbarker 2024-07-17 02:57:43 +09:00
48 changed files with 127 additions and 1279 deletions

View file

@ -6,10 +6,8 @@
"features": { "features": {
"ghcr.io/devcontainers/features/github-cli:1": {}, "ghcr.io/devcontainers/features/github-cli:1": {},
"ghcr.io/devcontainers-contrib/features/pre-commit:1": {}, "ghcr.io/devcontainers-contrib/features/pre-commit:1": {},
"./features/serenity": { "./features/ladybird": {
"llvm_version": 18, "llvm_version": 18,
"enable_ladybird": true,
"enable_serenity": true
}, },
"ghcr.io/devcontainers/features/desktop-lite": { "ghcr.io/devcontainers/features/desktop-lite": {
"password": "vscode", "password": "vscode",

View file

@ -0,0 +1,18 @@
{
"name": "Ladybird Development",
"id": "ladybird",
"version": "2.0.0",
"description": "Enable development of Ladybird libraries and applications",
"options": {
"llvm_version": {
"type": "string",
"proposals": [
17,
18,
"trunk"
],
"default": 18,
"description": "Select LLVM compiler version to use"
}
}
}

View file

@ -4,9 +4,6 @@ set -e
# Feature options # Feature options
LLVM_VERSION=${LLVM_VERSION:-18} LLVM_VERSION=${LLVM_VERSION:-18}
ENABLE_LADYBIRD=${ENABLE_LADYBIRD:-true}
ENABLE_SERENITY=${ENABLE_SERENITY:-true}
### Check distro ### Check distro
if [ ! -f /etc/lsb-release ]; then if [ ! -f /etc/lsb-release ]; then
@ -31,13 +28,7 @@ install_llvm_key() {
### Install packages ### Install packages
apt update -y apt update -y
apt install -y build-essential cmake ninja-build ccache shellcheck apt install -y build-essential cmake ninja-build ccache shellcheck libgl1-mesa-dev qt6-base-dev qt6-tools-dev-tools qt6-wayland qt6-multimedia-dev
if [ "${ENABLE_LADYBIRD}" = "true" ]; then
apt install -y libgl1-mesa-dev qt6-base-dev qt6-tools-dev-tools qt6-wayland qt6-multimedia-dev
fi
if [ "${ENABLE_SERENITY}" = "true" ]; then
apt install -y curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs genext2fs qemu-system-gui qemu-system-x86 qemu-utils rsync unzip texinfo libssl-dev
fi
### Ensure new enough host compiler is available ### Ensure new enough host compiler is available

View file

@ -1,30 +0,0 @@
{
"name": "Serenity Development",
"id": "serenity",
"version": "1.0.1",
"description": "Enable development of Serenity and Lagom libraries and applications",
"options": {
"llvm_version": {
"type": "string",
"proposals": [
15,
16,
17,
18,
"trunk"
],
"default": 18,
"description": "Select LLVM compiler version to use"
},
"enable_ladybird": {
"type": "boolean",
"default": true,
"description": "Install Qt6 packages for Ladybird development"
},
"enable_serenity": {
"type": "boolean",
"default": true,
"description": "Install packages for SerenityOS development"
}
}
}

View file

@ -6,6 +6,6 @@
// do not need to install all the prerequsite dependencies from scratch, // do not need to install all the prerequsite dependencies from scratch,
// getting you into your development environment faster! // getting you into your development environment faster!
{ {
"name": "SerenityOS (Pre-Built Image)", "name": "Ladybird (Pre-Built Image)",
"image": "ghcr.io/serenityos/serenity-devcontainer:base" "image": "ghcr.io/ladybirdwebbrowser/ladybird-devcontainer:base"
} }

3
.gitattributes vendored
View file

@ -10,6 +10,3 @@
*.pgm binary *.pgm binary
*.png binary *.png binary
*.ppm binary *.ppm binary
# Prevent port patches from being normalized
/Ports/**/patches/* -text

4
.github/CODEOWNERS vendored
View file

@ -1,9 +1,7 @@
/AK/CircularBuffer.* @timschumi /AK/CircularBuffer.* @timschumi
/AK/MaybeOwned.h @timschumi /AK/MaybeOwned.h @timschumi
/AK/*Stream.* @timschumi /AK/*Stream.* @timschumi
/Kernel/Devices/Audio @GMTA
/Lagom/Tools/CodeGenerators/LibWeb @AtkinsSJ /Lagom/Tools/CodeGenerators/LibWeb @AtkinsSJ
/Ports @timschumi
/Tests/LibCompress @timschumi /Tests/LibCompress @timschumi
/Toolchain @BertalanD /Toolchain @BertalanD
/Userland/Applications/Spreadsheet @alimpfard /Userland/Applications/Spreadsheet @alimpfard
@ -34,10 +32,8 @@
/Userland/Services/RequestServer @alimpfard /Userland/Services/RequestServer @alimpfard
/Userland/Services/SQLServer @trflynn89 /Userland/Services/SQLServer @trflynn89
/Userland/Services/WebDriver @trflynn89 /Userland/Services/WebDriver @trflynn89
/Userland/Shell @alimpfard
/Userland/Utilities/gzip.cpp @timschumi /Userland/Utilities/gzip.cpp @timschumi
/Userland/Utilities/lzcat.cpp @timschumi /Userland/Utilities/lzcat.cpp @timschumi
/Userland/Utilities/readelf.cpp @BertalanD
/Userland/Utilities/sql.cpp @trflynn89 /Userland/Utilities/sql.cpp @trflynn89
/Userland/Utilities/tar.cpp @timschumi /Userland/Utilities/tar.cpp @timschumi
/Userland/Utilities/unzip.cpp @timschumi /Userland/Utilities/unzip.cpp @timschumi

View file

@ -27,37 +27,15 @@ inputs:
description: 'Path to the SerenityOS ccache directory' description: 'Path to the SerenityOS ccache directory'
required: false required: false
default: '' default: ''
toolchain_ccache_path:
description: 'Path to the toolchain ccache directory'
required: false
default: ''
download_cache_path: download_cache_path:
description: 'Path to the download cache directory' description: 'Path to the download cache directory'
required: false required: false
default: 'caches' default: 'caches'
outputs: outputs:
qemu_cache_primary_key:
description: 'Primary key for the AArch64 QEMU cache'
value: ${{ steps.qemu-cache.outputs.cache-primary-key }}
qemu_cache_hit:
description: 'Whether the AArch64 QEMU cache was hit'
value: ${{ steps.qemu-cache.outputs.cache-hit }}
serenity_ccache_primary_key: serenity_ccache_primary_key:
description: 'Primary key for the Serenity ccache' description: 'Primary key for the Serenity ccache'
value: ${{ steps.serenity-ccache.outputs.cache-primary-key }} value: ${{ steps.serenity-ccache.outputs.cache-primary-key }}
toolchain_ccache_primary_key:
description: 'Primary key for the Toolchain ccache'
value: ${{ steps.toolchain-ccache.outputs.cache-primary-key }}
toolchain_prebuilt_primary_key:
description: 'Primary key for the toolchain cache'
value: ${{ steps.toolchain-prebuilt.outputs.cache-primary-key }}
toolchain_prebuilt_path:
description: 'Path to the prebuilt toolchain'
value: ${{ steps.toolchain-stamps.outputs.toolchain_path }}
toolchain_prebuilt_hit:
description: 'Whether the toolchain prebuilt cache was hit'
value: ${{ steps.toolchain-prebuilt.outputs.cache-hit }}
runs: runs:
using: "composite" using: "composite"
@ -68,64 +46,6 @@ runs:
run: | run: |
echo "timestamp=$(date -u "+%Y%m%d%H%M_%S")" >> "$GITHUB_OUTPUT" echo "timestamp=$(date -u "+%Y%m%d%H%M_%S")" >> "$GITHUB_OUTPUT"
- name: 'Toolchain Stamps'
shell: bash
id: 'toolchain-stamps'
if: ${{ inputs.arch != 'Lagom' }}
run: |
if ${{ inputs.toolchain == 'Clang' }} ; then
echo "toolchain_path=${{ github.workspace }}/Toolchain/Local/clang" >> "$GITHUB_OUTPUT"
hashed_files='${{ hashFiles('Toolchain/BuildClang.sh', 'Toolchain/Patches/llvm/*.patch', 'Toolchain/CMake/*.cmake', 'Userland/Libraries/LibC/**/*.h') }}'
echo "toolchain_stamp=${hashed_files}" >> "$GITHUB_OUTPUT"
source $GITHUB_WORKSPACE/Ports/llvm/package.sh
echo "toolchain_version=$(echo ${version} | cut -d'.' -f1)" >> "$GITHUB_OUTPUT"
elif ${{ inputs.toolchain == 'GNU' }} ; then
echo "toolchain_path=${{ github.workspace }}/Toolchain/Local/${{ inputs.arch }}" >> $GITHUB_OUTPUT
hashed_files='${{ hashFiles('Toolchain/BuildGNU.sh', 'Toolchain/Patches/binutils/*.patch', 'Toolchain/Patches/gcc/*.patch', 'Userland/Libraries/LibC/**/*.h') }}'
echo "toolchain_stamp=${hashed_files}" >> $GITHUB_OUTPUT
source $GITHUB_WORKSPACE/Ports/gcc/package.sh
echo "toolchain_version=$(echo ${version} | cut -d'.' -f1)" >> $GITHUB_OUTPUT
fi
- name: 'Toolchain Prebuilt Cache'
uses: actions/cache/restore@v4
id: 'toolchain-prebuilt'
if: ${{ inputs.arch != 'Lagom' }}
with:
path: ${{ steps.toolchain-stamps.outputs.toolchain_path }}
key: '"toolchain" | "${{ inputs.arch }}" | "${{ inputs.toolchain }}" | "${{ steps.toolchain-stamps.outputs.toolchain_stamp }}"'
# FIXME: Remove manually built QEMU when we bump QEMU to >=8.1.x
- name: 'AArch64 QEMU Cache'
id: 'qemu-cache'
uses: actions/cache/restore@v4
if: ${{ inputs.arch == 'aarch64' }}
with:
path: ${{ github.workspace }}/Toolchain/Local/qemu
key: ${{ runner.os }}-qemu-${{ hashFiles('Ports/qemu/version.sh', 'Toolchain/BuildQemu.sh') }}
- name: 'Toolchain Compiler Cache'
uses: actions/cache/restore@v4
id: 'toolchain-ccache'
if: ${{ inputs.toolchain_ccache_path != '' }}
with:
path: ${{ inputs.toolchain_ccache_path }}
key: '"toolchain ccache" | "${{ inputs.arch }}" | "${{ inputs.toolchain }}" | "${{ steps.toolchain-stamps.outputs.toolchain_version }}" | "${{ inputs.ccache_version }}" | ${{ steps.date-stamp.outputs.timestamp }}'
restore-keys: |
"toolchain ccache" | "${{ inputs.arch }}" | "${{ inputs.toolchain }}" | "${{ steps.toolchain-stamps.outputs.toolchain_version }}" | "${{ inputs.ccache_version }}"
- name: 'Configure Toolchain ccache'
if: ${{ inputs.toolchain_ccache_path != '' }}
shell: bash
run: |
CCACHE_DIR=${{ inputs.toolchain_ccache_path }} ccache -M 0
CCACHE_DIR=${{ inputs.toolchain_ccache_path }} ccache -s
CCACHE_DIR=${{ inputs.toolchain_ccache_path }} ccache -z
- name: 'Serenity Compiler Cache' - name: 'Serenity Compiler Cache'
uses: actions/cache/restore@v4 uses: actions/cache/restore@v4
id: 'serenity-ccache' id: 'serenity-ccache'

View file

@ -7,14 +7,6 @@ inputs:
description: 'Target Architecture to restore caches for' description: 'Target Architecture to restore caches for'
required: false required: false
default: 'x86_64' default: 'x86_64'
qemu_cache_primary_key:
description: 'Primary key for the AArch64 QEMU cache'
required: false
default: ''
qemu_cache_hit:
description: 'Whether the AArch64 QEMU cache was hit'
required: false
default: false
serenity_ccache_path: serenity_ccache_path:
description: 'Path to the SerenityOS ccache directory' description: 'Path to the SerenityOS ccache directory'
required: false required: false
@ -23,54 +15,10 @@ inputs:
description: 'Primary key for the Serenity ccache' description: 'Primary key for the Serenity ccache'
required: false required: false
default: '' default: ''
toolchain_ccache_path:
description: 'Path to the toolchain ccache directory'
required: false
default: ''
toolchain_ccache_primary_key:
description: 'Primary key for the Toolchain ccache'
required: false
default: ''
toolchain_prebuilt_path:
description: 'Path to the prebuilt toolchain'
required: false
default: ''
toolchain_prebuilt_primary_key:
description: 'Primary key for the toolchain cache'
required: false
default: ''
toolchain_prebuilt_hit:
description: 'Whether the toolchain prebuilt cache was hit'
required: false
default: false
runs: runs:
using: "composite" using: "composite"
steps: steps:
- name: 'Toolchain Prebuilt Cache'
uses: actions/cache/save@v4
# Do not waste time and storage space by updating the toolchain cache from a PR,
# as it would be discarded after being merged anyway.
if: ${{ github.event_name != 'pull_request' && !inputs.toolchain_prebuilt_hit && inputs.arch != 'Lagom' }}
with:
path: ${{ inputs.toolchain_prebuilt_path }}
key: ${{ inputs.toolchain_prebuilt_primary_key }}
# FIXME: Remove manually built QEMU when we bump QEMU to >=8.1.x
- name: 'AArch64 QEMU Cache'
uses: actions/cache/save@v4
if: ${{ github.event_name != 'pull_request' && !inputs.qemu_cache_hit && inputs.arch == 'aarch64' }}
with:
path: ${{ github.workspace }}/Toolchain/Local/qemu
key: ${{ inputs.qemu_cache_primary_key }}
- name: 'Toolchain Compiler Cache'
uses: actions/cache/save@v4
if: ${{ github.event_name != 'pull_request' && inputs.toolchain_ccache_path != '' }}
with:
path: ${{ inputs.toolchain_ccache_path }}
key: ${{ inputs.toolchain_ccache_primary_key }}
- name: 'Prune obsolete ccache files' - name: 'Prune obsolete ccache files'
shell: bash shell: bash
if: ${{ inputs.serenity_ccache_path != '' }} if: ${{ inputs.serenity_ccache_path != '' }}

View file

@ -42,19 +42,19 @@ runs:
echo "${{ github.workspace }}/wabt-1.0.23/bin" >> $GITHUB_PATH echo "${{ github.workspace }}/wabt-1.0.23/bin" >> $GITHUB_PATH
- name: 'Install JS dependencies' - name: 'Install JS dependencies'
if: ${{ inputs.os == 'Linux' || inputs.os == 'Serenity' }} if: ${{ inputs.os == 'Linux' }}
shell: bash shell: bash
run: sudo npm install -g prettier@2.7.1 run: sudo npm install -g prettier@2.7.1
- name: 'Install Python dependencies' - name: 'Install Python dependencies'
if: ${{ inputs.os == 'Linux' || inputs.os == 'Serenity' }} if: ${{ inputs.os == 'Linux' }}
shell: bash shell: bash
run: | run: |
python3 -m pip install --upgrade pip python3 -m pip install --upgrade pip
pip3 install flake8 requests six pip3 install flake8 requests six
- name: 'Install Dependencies' - name: 'Install Dependencies'
if: ${{ inputs.os == 'Serenity' }} if: ${{ inputs.os }}
shell: bash shell: bash
run: | run: |
set -e set -e
@ -65,20 +65,7 @@ runs:
sudo add-apt-repository ppa:ubuntu-toolchain-r/test sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update sudo apt-get update
sudo apt-get install clang-format-18 ccache e2fsprogs gcc-13 g++-13 libstdc++-13-dev libmpfr-dev libmpc-dev ninja-build optipng qemu-utils qemu-system-i386 unzip generate-ninja libegl1-mesa-dev sudo apt-get install clang-format-18 ccache e2fsprogs gcc-13 g++-13 libstdc++-13-dev libmpfr-dev libmpc-dev ninja-build optipng unzip generate-ninja libegl1-mesa-dev
if ${{ inputs.arch == 'aarch64' }}; then
# FIXME: Remove this when we no longer build our own Qemu binary.
sudo apt-get install libgtk-3-dev libpixman-1-dev libsdl2-dev libslirp-dev
fi
- name: Enable KVM group perms
if: ${{ inputs.os == 'Serenity' }}
shell: bash
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: 'Install Dependencies' - name: 'Install Dependencies'
if: ${{ inputs.os == 'macOS' || inputs.os == 'Android' }} if: ${{ inputs.os == 'macOS' || inputs.os == 'Android' }}

View file

@ -7,36 +7,8 @@ concurrency:
cancel-in-progress: true cancel-in-progress: true
jobs: jobs:
SerenityOS:
if: github.repository == 'SerenityOS/serenity'
strategy:
fail-fast: false
matrix:
toolchain: ['GNU', 'Clang']
os: [ubuntu-22.04]
arch: ['x86_64']
debug_options: ['NORMAL_DEBUG']
include:
- toolchain: 'GNU'
os: ubuntu-22.04
arch: 'aarch64'
debug_options: 'NORMAL_DEBUG'
- toolchain: 'GNU'
os: ubuntu-22.04
arch: 'x86_64'
debug_options: 'ALL_DEBUG'
uses: ./.github/workflows/serenity-template.yml
with:
toolchain: ${{ matrix.toolchain }}
os: ${{ matrix.os }}
arch: ${{ matrix.arch }}
debug_options: ${{ matrix.debug_options }}
Lagom: Lagom:
if: github.repository == 'SerenityOS/serenity' if: github.repository == 'LadybirdWebBrowser/ladybird'
strategy: strategy:
fail-fast: false fail-fast: false
@ -44,14 +16,20 @@ jobs:
os_name: ['Linux'] os_name: ['Linux']
os: [ubuntu-22.04] os: [ubuntu-22.04]
fuzzer: ['NO_FUZZ', 'FUZZ'] fuzzer: ['NO_FUZZ', 'FUZZ']
toolchain: ['Clang']
include: include:
- os_name: 'macOS' - os_name: 'macOS'
os: macos-14 os: macos-14
fuzzer: 'NO_FUZZ' fuzzer: 'NO_FUZZ'
toolchain: 'Clang'
- os_name: 'Linux'
os: ubuntu-22.04
fuzzer: 'NO_FUZZ'
toolchain: 'GNU'
uses: ./.github/workflows/lagom-template.yml uses: ./.github/workflows/lagom-template.yml
with: with:
toolchain: 'Clang' toolchain: ${{ matrix.toolchain }}
os_name: ${{ matrix.os_name }} os_name: ${{ matrix.os_name }}
os: ${{ matrix.os }} os: ${{ matrix.os }}
fuzzer: ${{ matrix.fuzzer }} fuzzer: ${{ matrix.fuzzer }}

View file

@ -17,7 +17,7 @@ permissions:
jobs: jobs:
build: build:
if: github.repository == 'SerenityOS/serenity' if: github.repository == 'LadybirdWebBrowser/ladybird'
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
@ -34,6 +34,6 @@ jobs:
- name: Build Base Dev Container Image - name: Build Base Dev Container Image
uses: devcontainers/ci@v0.3 uses: devcontainers/ci@v0.3
with: with:
imageName: ghcr.io/serenityos/serenity-devcontainer imageName: ghcr.io/ladybirdwebbrowser/ladybird-devcontainer
imageTag: base,latest imageTag: base,latest
push: always push: always

View file

@ -1,17 +0,0 @@
name: Discord notifications
on: [push, pull_request_target]
jobs:
notify_discord:
runs-on: ubuntu-22.04
if: always() && github.repository == 'SerenityOS/serenity' && (github.event_name == 'pull_request_target' || (github.event_name == 'push' && github.ref == 'refs/heads/master'))
steps:
- name: Discord action notification
env:
DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
CUSTOM_GITHUB_EVENT_NAME: ${{ github.event_name == 'pull_request_target' && 'pull_request' || github.event_name }} # fake the event type as discord doesn't know how to parse the special pull_request_target context
uses: IdanHo/action-discord@754598254f288e6d8e9fca637832e3c163515ba8
# FIXME: Find a way to notify on 'ready_for_review', but rate-limited to once/twice per day.
if: ${{ (github.event['pull_request'] && github.event['action'] == 'opened') || github.event['commits'] }}

View file

@ -12,7 +12,7 @@ on:
jobs: jobs:
label_pull_request: label_pull_request:
runs-on: ubuntu-22.04 runs-on: ubuntu-22.04
if: always() && github.repository == 'SerenityOS/serenity' if: always() && github.repository == 'LadybirdWebBrowser/ladybird'
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4

View file

@ -8,7 +8,8 @@ env:
jobs: jobs:
run_and_update_results: run_and_update_results:
runs-on: self-hosted runs-on: self-hosted
if: always() && github.repository == 'SerenityOS/serenity' && github.ref == 'refs/heads/master' if: false
#if: always() && github.repository == 'LadybirdWebBrowser/ladybird' && github.ref == 'refs/heads/master'
concurrency: libjs-test262 concurrency: libjs-test262
@ -18,7 +19,7 @@ jobs:
echo "Cleaning up previous run" echo "Cleaning up previous run"
rm -rf "${{ github.workspace }}/*" rm -rf "${{ github.workspace }}/*"
- name: Checkout SerenityOS/serenity - name: Checkout LadybirdWebBrowser/ladybird
uses: actions/checkout@v4 uses: actions/checkout@v4
- name: Checkout SerenityOS/libjs-test262 - name: Checkout SerenityOS/libjs-test262

View file

@ -8,7 +8,7 @@ on: [pull_request_target]
jobs: jobs:
lint_commits: lint_commits:
runs-on: ubuntu-22.04 runs-on: ubuntu-22.04
if: always() && github.repository == 'SerenityOS/serenity' if: always() && github.repository == 'LadybirdWebBrowser/ladybird'
steps: steps:
- name: Lint PR commits - name: Lint PR commits
@ -91,4 +91,4 @@ jobs:
env: env:
GITHUB_TOKEN: ${{ secrets.BUGGIEBOT_TOKEN }} GITHUB_TOKEN: ${{ secrets.BUGGIEBOT_TOKEN }}
with: with:
msg: "Hello!\n\nOne or more of the commit messages in this PR do not match the SerenityOS [code submission policy](https://github.com/SerenityOS/serenity/blob/master/CONTRIBUTING.md#code-submission-policy), please check the `lint_commits` CI job for more details on which commits were flagged and why.\nPlease do not close this PR and open another, instead modify your commit message(s) with [git commit --amend](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message) and force push those changes to update this PR." msg: "Hello!\n\nOne or more of the commit messages in this PR do not match the SerenityOS [code submission policy](https://github.com/LadybirdWebBrowser/ladybird/blob/master/CONTRIBUTING.md#code-submission-policy), please check the `lint_commits` CI job for more details on which commits were flagged and why.\nPlease do not close this PR and open another, instead modify your commit message(s) with [git commit --amend](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message) and force push those changes to update this PR."

View file

@ -1,28 +0,0 @@
name: Generate man pages
on:
push:
paths:
- "Base/usr/share/man/**"
- "Meta/Websites/man.serenityos.org/**"
jobs:
convert_using_pandoc:
runs-on: ubuntu-22.04
if: always() && github.repository == 'SerenityOS/serenity' && github.ref == 'refs/heads/master'
steps:
- uses: actions/checkout@v4
- uses: r-lib/actions/setup-pandoc@v2
with:
pandoc-version: '2.13'
- name: Actually build website
run: ./Meta/build-manpages-website.sh
- name: Deploy to GitHub pages
uses: JamesIves/github-pages-deploy-action@v4.6.1
with:
git-config-name: BuggieBot
git-config-email: buggiebot@serenityos.org
branch: master
repository-name: SerenityOS/manpages-website
token: ${{ secrets.BUGGIEBOT_TOKEN }}
folder: output

View file

@ -18,7 +18,7 @@ concurrency:
jobs: jobs:
CI: CI:
runs-on: ${{ matrix.os }} runs-on: ${{ matrix.os }}
if: always() && github.repository == 'SerenityOS/serenity' && github.ref == 'refs/heads/master' if: always() && github.repository == 'LadybirdWebBrowser/ladybird' && github.ref == 'refs/heads/master'
strategy: strategy:
fail-fast: false fail-fast: false
matrix: matrix:

View file

@ -1,36 +0,0 @@
name: Nightly CI
on:
# Automatically run at the end of every day.
schedule:
- cron: '0 0 * * *'
concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || format('{0}-{1}', github.ref, github.run_number) }}
cancel-in-progress: true
jobs:
CodeCoverage:
if: always() && github.repository == 'SerenityOS/serenity' && github.ref == 'refs/heads/master'
strategy:
fail-fast: false
uses: ./.github/workflows/serenity-template.yml
with:
toolchain: 'Clang'
os: ubuntu-22.04
arch: 'x86_64'
coverage: 'ON'
LagomGCC:
if: always() && github.repository == 'SerenityOS/serenity' && github.ref == 'refs/heads/master'
strategy:
fail-fast: false
uses: ./.github/workflows/lagom-template.yml
with:
toolchain: 'GNU'
os_name: 'Linux'
os: ubuntu-22.04

View file

@ -9,7 +9,7 @@ env:
jobs: jobs:
build-and-package: build-and-package:
runs-on: ${{ matrix.os }} runs-on: ${{ matrix.os }}
if: always() && github.repository == 'SerenityOS/serenity' && github.ref == 'refs/heads/master' if: always() && github.repository == 'LadybirdWebBrowser/ladybird' && github.ref == 'refs/heads/master'
strategy: strategy:
fail-fast: false fail-fast: false
matrix: matrix:
@ -26,7 +26,7 @@ jobs:
cancel-in-progress: true cancel-in-progress: true
steps: steps:
- name: Checkout SerenityOS/serenity - name: Checkout LadybirdWebBrowser/ladybird
uses: actions/checkout@v4 uses: actions/checkout@v4
- name: "Set up environment" - name: "Set up environment"
@ -88,5 +88,5 @@ jobs:
uses: actions/upload-artifact@v4 uses: actions/upload-artifact@v4
with: with:
name: serenity-js-${{ matrix.package_type }} name: serenity-js-${{ matrix.package_type }}
path: Build/serenity-js*.tar.gz path: Build/ladybird-js*.tar.gz
retention-days: 7 retention-days: 7

View file

@ -1,209 +0,0 @@
name: SerenityOS Template
on:
workflow_call:
inputs:
toolchain:
required: true
type: string
os:
required: true
type: string
arch:
required: true
type: string
debug_options:
required: false
type: string
default: 'NORMAL_DEBUG'
coverage:
required: false
type: string
default: 'OFF'
env:
# runner.workspace = /home/runner/work/serenity
# github.workspace = /home/runner/work/serenity/serenity
SERENITY_SOURCE_DIR: ${{ github.workspace }}
SERENITY_CCACHE_DIR: ${{ github.workspace }}/.ccache
TOOLCHAIN_CCACHE_DIR: ${{ github.workspace }}/Toolchain/.ccache
jobs:
CI:
runs-on: ${{ inputs.os }}
steps:
# Pull requests can trail behind `master` and can cause breakage if merging before running the CI checks on an updated branch.
# Luckily, GitHub creates and maintains a merge branch that is updated whenever the target or source branch is modified. By
# checking this branch out, we gain a stabler `master` at the cost of reproducibility.
- uses: actions/checkout@v4
if: ${{ github.event_name != 'pull_request' }}
- uses: actions/checkout@v4
if: ${{ github.event_name == 'pull_request' }}
with:
ref: refs/pull/${{ github.event.pull_request.number }}/merge
- name: Set Up Environment
uses: ./.github/actions/setup
with:
os: 'Serenity'
arch: ${{ inputs.arch }}
# === PREPARE FOR BUILDING ===
- name: Lint
run: ${{ github.workspace }}/Meta/lint-ci.sh
- name: Restore Caches
uses: ./.github/actions/cache-restore
id: 'cache-restore'
with:
os: 'Serenity'
arch: ${{ inputs.arch }}
toolchain: ${{ inputs.toolchain }}
cache_key_extra: ${{ inputs.debug_options }}-COVERAGE_${{ inputs.coverage }}
serenity_ccache_path: ${{ env.SERENITY_CCACHE_DIR }}
toolchain_ccache_path: ${{ env.TOOLCHAIN_CCACHE_DIR }}
download_cache_path: ${{ github.workspace }}/Build/caches
- name: Assign Build Parameters
id: 'build-parameters'
run: |
if ${{ inputs.toolchain == 'Clang' }} ; then
echo "build_directory=${{ github.workspace }}/Build/${{ inputs.arch }}clang" >> "$GITHUB_OUTPUT"
elif ${{ inputs.toolchain == 'GNU' }} ; then
echo "build_directory=${{ github.workspace }}/Build/${{ inputs.arch }}" >> "$GITHUB_OUTPUT"
fi
- name: Build Toolchain
if: ${{ !steps.cache-restore.outputs.toolchain_prebuilt_hit }}
run: |
${{ github.workspace }}/Toolchain/Build${{ inputs.toolchain }}.sh --ci
env:
ARCH: ${{ inputs.arch}}
CCACHE_DIR: ${{ env.TOOLCHAIN_CCACHE_DIR }}
- name: Build AArch64 Qemu
if: ${{ inputs.arch == 'aarch64' && !steps.cache-restore.outputs.qemu_cache_hit }}
run: ${{ github.workspace }}/Toolchain/BuildQemu.sh
env:
CCACHE_DIR: ${{ env.TOOLCHAIN_CCACHE_DIR }}
- name: Create Build Environment
if: ${{ inputs.debug_options == 'ALL_DEBUG' }}
# Build the entire project with all available debug options turned on, to prevent code rot.
# However, it is unwieldy and slow to run tests with them enabled, so we will build twice.
run: |
cmake -S Meta/CMake/Superbuild -B Build/superbuild -GNinja \
-DSERENITY_ARCH=${{ inputs.arch }} \
-DSERENITY_TOOLCHAIN=${{ inputs.toolchain }} \
-DBUILD_LAGOM=ON \
-DCMAKE_C_COMPILER=gcc-13 \
-DCMAKE_CXX_COMPILER=g++-13 \
-DENABLE_ALL_DEBUG_FACILITIES=ON \
-DENABLE_PCI_IDS_DOWNLOAD=OFF \
-DENABLE_USB_IDS_DOWNLOAD=OFF
env:
CCACHE_DIR: ${{ env.SERENITY_CCACHE_DIR }}
- name: Create Build Environment
if: ${{ inputs.debug_options == 'NORMAL_DEBUG' }}
working-directory: ${{ github.workspace }}
# Note that we do not set BUILD_LAGOM for the normal debug build
# We build and run the Lagom tests in a separate job, and sanitizer builds take a good while longer than non-sanitized.
run: |
cmake -S Meta/CMake/Superbuild -B Build/superbuild -GNinja \
-DSERENITY_ARCH=${{ inputs.arch }} \
-DSERENITY_TOOLCHAIN=${{ inputs.toolchain }} \
-DCMAKE_C_COMPILER=gcc-13 \
-DCMAKE_CXX_COMPILER=g++-13 \
-DENABLE_UNDEFINED_SANITIZER=ON \
-DUNDEFINED_BEHAVIOR_IS_FATAL=ON \
-DENABLE_USERSPACE_COVERAGE_COLLECTION=${{ inputs.coverage }} \
-DDUMP_REGIONS_ON_CRASH=ON \
-DENABLE_PCI_IDS_DOWNLOAD=OFF \
-DENABLE_USB_IDS_DOWNLOAD=OFF
env:
CCACHE_DIR: ${{ env.SERENITY_CCACHE_DIR }}
# === BUILD ===
- name: Build Serenity and Tests
working-directory: ${{ github.workspace }}/Build/superbuild
run: cmake --build .
env:
CCACHE_DIR: ${{ env.SERENITY_CCACHE_DIR }}
- name: Save Caches
uses: ./.github/actions/cache-save
with:
arch: ${{ inputs.arch }}
qemu_cache_primary_key: ${{ steps.cache-restore.outputs.qemu_cache_primary_key }}
qemu_cache_hit: ${{ steps.cache-restore.outputs.qemu_cache_hit }}
serenity_ccache_path: ${{ env.SERENITY_CCACHE_DIR }}
serenity_ccache_primary_key: ${{ steps.cache-restore.outputs.serenity_ccache_primary_key }}
toolchain_ccache_path: ${{ env.TOOLCHAIN_CCACHE_DIR }}
toolchain_ccache_primary_key: ${{ steps.cache-restore.outputs.toolchain_ccache_primary_key }}
toolchain_prebuilt_path: ${{ steps.cache-restore.outputs.toolchain_prebuilt_path }}
toolchain_prebuilt_primary_key: ${{ steps.cache-restore.outputs.toolchain_prebuilt_primary_key }}
toolchain_prebuilt_hit: ${{ steps.cache-restore.outputs.toolchain_prebuilt_hit }}
# === TEST ===
- name: Create Serenity Rootfs
if: ${{ inputs.debug_options == 'NORMAL_DEBUG' }}
working-directory: ${{ steps.build-parameters.outputs.build_directory }}
run: ninja install && ninja qemu-image
- name: Run On-Target Tests
if: ${{ inputs.debug_options == 'NORMAL_DEBUG' && inputs.arch != 'aarch64' }}
working-directory: ${{ steps.build-parameters.outputs.build_directory }}
env:
SERENITY_QEMU_CPU: "max,vmx=off"
SERENITY_KERNEL_CMDLINE: "graphics_subsystem_mode=off panic=shutdown system_mode=self-test"
SERENITY_RUN: "ci"
run: |
echo "::group::ninja run # Qemu output"
ninja run
echo "::endgroup::"
echo "::group::Verify Output File"
mkdir fsmount
sudo mount -t ext2 -o loop,rw _disk_image fsmount
echo "Results: "
sudo cat fsmount/home/anon/test-results.log
if ! sudo grep -q "Failed: 0" fsmount/home/anon/test-results.log
then
echo "::error:: :^( Tests failed, failing job"
exit 1
fi
echo "::endgroup::"
timeout-minutes: 60
- name: Print Target Logs
# Extremely useful if Serenity hangs trying to run one of the tests
if: ${{ !cancelled() && inputs.debug_options == 'NORMAL_DEBUG'}}
working-directory: ${{ steps.build-parameters.outputs.build_directory }}
run: '[ ! -e debug.log ] || cat debug.log'
# === COVERAGE ===
- name: Aggregate Coverage Results
if: ${{ inputs.coverage == 'ON' }}
working-directory: ${{ github.workspace }}
run: ./Meta/analyze-qemu-coverage.sh
env:
SERENITY_TOOLCHAIN: ${{ matrix.toolchain }}
SERENITY_ARCH: ${{ matrix.arch }}
# FIXME: Deploy the static html pages somewhere
# FIXME: Alter script to also (instead?) produce a raw coverage.txt file for ingestion into sonar cloud
# Note: tmp_profile_data/Coverage.profdata has the entire combined profile data, but creating the raw txt requires
# all of the instrumented binaries and the profdata file.
- name: Upload Coverage Results
if: ${{ inputs.coverage == 'ON' }}
uses: actions/upload-artifact@v4
with:
name: serenity-coverage
path: ${{ steps.build-parameters.outputs.build_directory }}/reports
retention-days: 90

View file

@ -1,41 +0,0 @@
name: Social media notifications
on: [ push ]
jobs:
notify_twitter:
runs-on: ubuntu-22.04
if: always() && github.repository == 'SerenityOS/serenity' && github.ref == 'refs/heads/master'
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
- run: npm i twit
- run: |
node ${{ github.workspace }}/Meta/tweet-commits.js << 'EOF'
${{ toJSON(github.event) }}
EOF
env:
CONSUMER_KEY: ${{ secrets.CONSUMER_KEY }}
CONSUMER_SECRET: ${{ secrets.CONSUMER_SECRET }}
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
ACCESS_TOKEN_SECRET: ${{ secrets.ACCESS_TOKEN_SECRET }}
notify_mastodon:
runs-on: ubuntu-22.04
if: always() && github.repository == 'SerenityOS/serenity' && github.ref == 'refs/heads/master'
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '14'
- run: npm i mastodon
- run: |
node ${{ github.workspace }}/Meta/toot-commits.js << 'EOF'
${{ toJSON(github.event) }}
EOF
env:
ACCESS_TOKEN: ${{ secrets.MASTODON_ACCESS_TOKEN }}

View file

@ -10,11 +10,11 @@ concurrency: wasm
jobs: jobs:
build: build:
runs-on: ubuntu-22.04 runs-on: ubuntu-22.04
if: github.repository == 'SerenityOS/serenity' if: false
strategy: strategy:
fail-fast: false fail-fast: false
steps: steps:
- name: Checkout SerenityOS/serenity - name: Checkout LadybirdWebBrowser/ladybird
uses: actions/checkout@v4 uses: actions/checkout@v4
- name: Checkout SerenityOS/libjs-data libjs-wasm - name: Checkout SerenityOS/libjs-data libjs-wasm

View file

@ -8,14 +8,6 @@ repos:
stages: [ commit ] stages: [ commit ]
language: system language: system
- id: meta-lint-ports
name: Running Meta/lint-ports.py to ensure changes will pass linting on CI
entry: Meta/lint-ports.py
pass_filenames: false
files: ^Ports/
stages: [ commit ]
language: system
- id: meta-lint-commit - id: meta-lint-commit
name: Lint commit message to ensure it will pass the commit linting on CI name: Lint commit message to ensure it will pass the commit linting on CI
entry: Meta/lint-commit.sh entry: Meta/lint-commit.sh

View file

@ -1,29 +1,26 @@
# Contributing to SerenityOS # Contributing to Ladybird
When contributing to SerenityOS, make sure that the changes you wish to make are in line with the project direction. If you are not sure about this, open an issue first, so we can discuss it. When contributing to Ladybird, make sure that the changes you wish to make are in line with the project direction. If you are not sure about this, open an issue first, so we can discuss it.
**For your first couple of PRs, start with something small to get familiar with the project and its development processes. Please do not start by adding a new application, library or other large component.** **For your first couple of PRs, start with something small to get familiar with the project and its development processes. Please do not start by adding a large component.**
Everyone is welcome to work on the project, and while we have lots of fun, it's a serious kind of fun. :^) Everyone is welcome to work on the project, and while we have lots of fun, it's a serious kind of fun. :^)
## Communication ## Communication
Join our Discord server: [SerenityOS Discord](https://discord.gg/serenityos) Join [our Discord server](https://discord.gg/nvfjVJ4Svh) to participate in development discussion.
## Issue policy ## Issue policy
Unlike many other software projects, SerenityOS is not concerned with gaining the largest possible userbase. Its target audience is its own developers. As such, we have limited interest in feature requests from non-contributors. Please file any bugs you find, keeping the following in mind:
That said, please do file any bugs you find, keeping the following in mind:
* One issue per bug. Putting multiple things in the same issue makes both discussion and completion unnecessarily complicated. * One issue per bug. Putting multiple things in the same issue makes both discussion and completion unnecessarily complicated.
* No build issues (or other support requests). If the GitHub Actions CI build succeeds, the build problem is most likely on your side. Work it out locally, or ask in the `#build-problems` channel on Discord. * No build issues (or other support requests). If the GitHub Actions CI build succeeds, the build problem is most likely on your side. Work it out locally, or ask in the `#build-problems` channel on Discord.
* Don't comment on issues just to add a joke or irrelevant commentary. Hundreds of people get notified about comments so let's keep them relevant. * Don't comment on issues just to add a joke or irrelevant commentary. Hundreds of people get notified about comments so let's keep them relevant.
* For bare metal issues, please include the complete debug log from the serial console and what you tried to do to solve the issue before opening the issue. Don't forget to add the hardware model of your machine and relevant details about it, to help us diagnose what the problem is.
## Human language policy ## Human language policy
In SerenityOS, we treat human language as seriously as we do programming language. In Ladybird, we treat human language as seriously as we do programming language.
The following applies to all user-facing strings, code, comments, and commit messages: The following applies to all user-facing strings, code, comments, and commit messages:
@ -43,14 +40,14 @@ Nobody is perfect, and sometimes we mess things up. That said, here are some goo
**Do:** **Do:**
* Write in idiomatic SerenityOS C++23, using the `AK` containers in all code. * Write in idiomatic SerenityOS-style C++23, using the `AK` containers in all code.
* Conform to the project coding style found in [CodingStyle.md](https://github.com/SerenityOS/serenity/blob/master/Documentation/CodingStyle.md). Use `clang-format` (version 18 or later) to automatically format C++ files. See [AdvancedBuildInstructions.md](https://github.com/SerenityOS/serenity/blob/master/Documentation/AdvancedBuildInstructions.md#clang-format-updates) for instructions on how to get an up-to-date version if your OS distribution does not ship clang-format-18. * Conform to the project coding style found in [CodingStyle.md](https://github.com/LadybirdWebBrowser/ladybird/blob/master/Documentation/CodingStyle.md). Use `clang-format` (version 18 or later) to automatically format C++ files. See [AdvancedBuildInstructions.md](https://github.com/LadybirdWebBrowser/ladybird/blob/master/Documentation/AdvancedBuildInstructions.md#clang-format-updates) for instructions on how to get an up-to-date version if your OS distribution does not ship clang-format-18.
* Choose expressive variable, function and class names. Make it as obvious as possible what the code is doing. * Choose expressive variable, function and class names. Make it as obvious as possible what the code is doing.
* Split your changes into separate, atomic commits (i.e. A commit per feature or fix, where the build, tests and the system are all functioning). * Split your changes into separate, atomic commits (i.e. A commit per feature or fix, where the build, tests and the system are all functioning).
* Make sure your commits are rebased on the master branch. * Make sure your commits are rebased on the master branch.
* Wrap your commit messages at 72 characters. * Wrap your commit messages at 72 characters.
* The first line of the commit message is the subject line, and must have the format "Category: Brief description of what's being changed". The category should be the name of a library, application, service, utility, etc. * The first line of the commit message is the subject line, and must have the format "Category: Brief description of what's being changed". The category should be the name of a library, application, service, utility, etc.
* Examples: `LibAudio`, `HackStudio`, `Base`, `Kernel`, `ConfigServer`, `cat` * Examples: `LibAudio`, `WebContent`, `CI`, `AK`, `RequestServer`, `js`
* Don't use a category like "`Userland`" or "`Utilities`", except for generic changes that affect a large portion of code within these directories. * Don't use a category like "`Userland`" or "`Utilities`", except for generic changes that affect a large portion of code within these directories.
* Don't use specific component names, e.g. C++ class names, as the category either - mention them in the summary instead. E.g. `LibGUI: Brief description of what's being changed in FooWidget` rather than `FooWidget: Brief description of what's being changed` * Don't use specific component names, e.g. C++ class names, as the category either - mention them in the summary instead. E.g. `LibGUI: Brief description of what's being changed in FooWidget` rather than `FooWidget: Brief description of what's being changed`
* Several categories may be combined with `+`, e.g. `LibJS+LibWeb+Browser: ...` * Several categories may be combined with `+`, e.g. `LibJS+LibWeb+Browser: ...`
@ -107,7 +104,7 @@ Maintainership is by invitation only and does not correlate with any particular
Yes, we have a "stalebot" that will mark untouched PRs as "stale" after 21 days, and close them after another 7 days if nothing happens. Yes, we have a "stalebot" that will mark untouched PRs as "stale" after 21 days, and close them after another 7 days if nothing happens.
### Are there specific people to reach out to for different subsystems (e.g. Kernel, Browser, GUI, etc)? ### Are there specific people to reach out to for different subsystems (e.g. Networking, GUI, CSS, etc)?
In theory, the best person to speak with is whoever wrote most code adjacent to what you're working on. In practice, asking in one of the development channels on Discord is usually easier/better, since that allows many people to join the discussion. In theory, the best person to speak with is whoever wrote most code adjacent to what you're working on. In practice, asking in one of the development channels on Discord is usually easier/better, since that allows many people to join the discussion.

View file

@ -2,38 +2,13 @@
This file covers a few advanced scenarios that go beyond what the basic build guide provides. This file covers a few advanced scenarios that go beyond what the basic build guide provides.
## Customizing the disk image
To add, modify or remove files of the disk image's file system, e.g. to change the default keyboard layout, you can create a shell script with the name `sync-local.sh` in the project root, with content like this:
```sh
#!/bin/sh
set -e
cat << 'EOF' > mnt/etc/Keyboard.ini
[Mapping]
Keymaps=de
EOF
# Add a file in anon's home dir
cp /somewhere/on/your/system/file.txt mnt/home/anon
```
This will configure your keymap to German (`de`) instead of US English. See [`Base/res/keymaps/`](../Base/res/keymaps/) for a full list. Note that the `keymap` program itself will also modify the `/etc/Keyboard.ini` config file, but this way the change will persist across image rebuilds.
## 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/serenity.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>`:
- `ninja limine-image`: Builds a disk image (`limine_disk_image`) with Limine
- `ninja grub-image`: Builds a disk image (`grub_disk_image`) with GRUB
- `ninja extlinux-image`: Builds a disk image (`extlinux_disk_image`) with extlinux
- `ninja check-style`: Runs the same linters the CI does to verify project style on changed files - `ninja check-style`: Runs the same linters the CI does to verify project style on changed files
- `ninja install-ports`: Copies the entire ports tree into the installed rootfs for building ports in Serenity
- `ninja lint-shell-scripts`: Checks style of shell scripts in the source tree with shellcheck - `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 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. - `ninja configure-components`: See the [Component Configuration](#component-configuration) section below.
@ -41,10 +16,7 @@ directory to `Build/x86_64` and then running `ninja <target>`:
## CMake build options ## CMake build options
There are some optional features that can be enabled during compilation that are intended to help with specific types of development work or introduce experimental features. Currently, the following build options are available: There are some optional features that can be enabled during compilation that are intended to help with specific types of development work or introduce experimental features. Currently, the following build options are available:
- `ENABLE_ADDRESS_SANITIZER` and `ENABLE_KERNEL_ADDRESS_SANITIZER`: builds in runtime checks for memory corruption bugs (like buffer overflows and memory leaks) in Lagom test cases and the kernel, respectively. - `ENABLE_ADDRESS_SANITIZER`: builds in runtime checks for memory corruption bugs (like buffer overflows and memory leaks) in Lagom test cases.
- `ENABLE_KERNEL_UNDEFINED_SANITIZER`: builds in runtime checks for detecting undefined behavior in the kernel.
- `ENABLE_KERNEL_COVERAGE_COLLECTION`: enables the KCOV API and kernel coverage collection instrumentation. Only useful for coverage guided kernel fuzzing.
- `ENABLE_USERSPACE_COVERAGE_COLLECTION`: enables coverage collection instrumentation for userspace. Currently only works with a Clang build.
- `ENABLE_MEMORY_SANITIZER`: enables runtime checks for uninitialized memory accesses in Lagom test cases. - `ENABLE_MEMORY_SANITIZER`: enables runtime checks for uninitialized memory accesses in Lagom test cases.
- `ENABLE_UNDEFINED_SANITIZER`: builds in runtime checks for [undefined behavior](https://en.wikipedia.org/wiki/Undefined_behavior) (like null pointer dereferences and signed integer overflows) in Lagom and the SerenityOS userland. - `ENABLE_UNDEFINED_SANITIZER`: builds in runtime checks for [undefined behavior](https://en.wikipedia.org/wiki/Undefined_behavior) (like null pointer dereferences and signed integer overflows) in Lagom and the SerenityOS userland.
- `UNDEFINED_BEHAVIOR_IS_FATAL`: makes all undefined behavior sanitizer errors non-recoverable. This option reduces the performance overhead of `ENABLE_UNDEFINED_SANITIZER`. - `UNDEFINED_BEHAVIOR_IS_FATAL`: makes all undefined behavior sanitizer errors non-recoverable. This option reduces the performance overhead of `ENABLE_UNDEFINED_SANITIZER`.
@ -52,27 +24,21 @@ There are some optional features that can be enabled during compilation that are
- `ENABLE_FUZZERS`: builds [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. - `ENABLE_FUZZERS`: builds [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system.
- `ENABLE_FUZZERS_LIBFUZZER`: builds Clang libFuzzer-based [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. - `ENABLE_FUZZERS_LIBFUZZER`: builds Clang libFuzzer-based [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system.
- `ENABLE_FUZZERS_OSSFUZZ`: builds OSS-Fuzz compatible [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system. - `ENABLE_FUZZERS_OSSFUZZ`: builds OSS-Fuzz compatible [fuzzers](../Meta/Lagom/ReadMe.md#fuzzing) for various parts of the system.
- `ENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS`: sets -Og and -ggdb3 compile options for building the Kernel. Allows for easier debugging of Kernel code. By default, the Kernel is built with -O2 instead.
- `ENABLE_ALL_THE_DEBUG_MACROS`: used for checking whether debug code compiles on CI. This should not be set normally, as it clutters the console output and makes the system run very slowly. Instead, enable only the needed debug macros, as described below. - `ENABLE_ALL_THE_DEBUG_MACROS`: used for checking whether debug code compiles on CI. This should not be set normally, as it clutters the console output and makes the system run very slowly. Instead, enable only the needed debug macros, as described below.
- `ENABLE_ALL_DEBUG_FACILITIES`: used for checking whether debug code compiles on CI. Enables both `ENABLE_ALL_THE_DEBUG_MACROS` and `ENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS`.
- `ENABLE_COMPILETIME_FORMAT_CHECK`: checks for the validity of `std::format`-style format string during compilation. Enabled by default. - `ENABLE_COMPILETIME_FORMAT_CHECK`: checks for the validity of `std::format`-style format string during compilation. Enabled by default.
- `ENABLE_PCI_IDS_DOWNLOAD`: downloads the [`pci.ids` database](https://pci-ids.ucw.cz/) that contains information about PCI devices at build time, if not already present. Enabled by default.
- `BUILD_LAGOM`: builds [Lagom](../Meta/Lagom/ReadMe.md), which makes various SerenityOS libraries and programs available on the host system. - `BUILD_LAGOM`: builds [Lagom](../Meta/Lagom/ReadMe.md), which makes various SerenityOS libraries and programs available on the host system.
- `ENABLE_KERNEL_LTO`: builds the kernel with link-time optimization.
- `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_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. - `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`` - `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_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. - `INCLUDE_FLAC_SPEC_TESTS`: downloads and includes the xiph.org FLAC test suite.
- `SERENITY_TOOLCHAIN`: Specifies whether to use the established GNU toolchain, or the experimental Clang-based toolchain for building SerenityOS. See the [Clang-based toolchain](#clang-based-toolchain) section below.
- `SERENITY_ARCH`: Specifies which architecture to build for. Currently supported options are `x86_64`, `aarch64`, `riscv64`.
- `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_<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 - `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. - `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_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. - `ENABLE_ACCELERATED_GRAPHICS`: builds features that use accelerated graphics APIs to speed up painting and drawing using native graphics libraries.
Many parts of the SerenityOS codebase have debug functionality, mostly consisting of additional messages printed to the debug console. This is done via the `<component_name>_DEBUG` macros, which can be enabled individually at build time. They are listed in [this file](../Meta/CMake/all_the_debug_macros.cmake). Many parts of the codebase have debug functionality, mostly consisting of additional messages printed to the debug console. This is done via the `<component_name>_DEBUG` macros, which can be enabled individually at build time. They are listed in [this file](../Meta/CMake/all_the_debug_macros.cmake).
To toggle or change a build option, see the [CMake Cache Manipulation](#cmake-cache-manipulation) section below. To toggle or change a build option, see the [CMake Cache Manipulation](#cmake-cache-manipulation) section below.
@ -98,73 +64,6 @@ $ cmake -B Build/x86_64 -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 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). [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).
## SuperBuild configuration
Serenity uses host tools written in idiomatic Serenity C++ to generate code and data for the main target build.
The "SuperBuild" pattern helps to separate the host build of core Serenity libraries from the target build of the
entire operating system environment. The SuperBuild allows clear separation of the host and target builds in the project's CMakeLists
and unifies the approach taken towards different compiler toolchains and architectures.
The recommended way to build and run the system, `./Meta/serenity.sh run`, invokes the SuperBuild equivalently to the commands below:
```console
$ cmake -GNinja -S Meta/CMake/Superbuild -B Build/superbuild-x86_64 -DSERENITY_ARCH=x86_64 -DSERENITY_TOOLCHAIN=GNU
$ cmake --build Build/superbuild-x86_64
$ ninja -C Build/x86_64 setup-and-run
```
The CMake configuration of the `superbuild-<arch>` directory configures two [ExternalProjects](https://cmake.org/cmake/help/latest/module/ExternalProject.html).
The first project is `lagom`, which is the host build of the project. For more information on Lagom, see the [Lagom ReadMe](../Meta/Lagom/ReadMe.md). It is used
to build all the code generators and other host tools needed for the main Serenity build. The second project is the main build, which compiles the system for the
target architecture using the selected toolchain.
The `superbuild-<arch>` configuration also generates the [CMake toolchain file](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling)
for the selected compiler toolchain and architecture via the `-DSERENITY_ARCH` and `-DSERENITY_TOOLCHAIN` arguments to the SuperBuild configuration step.
The Serenity project depends on the install step of the Lagom build, as it uses [find_package](https://cmake.org/cmake/help/latest/command/find_package.html) to locate
the host tools for use in the code generation custom commands.
The SuperBuild build steps are roughly equivalent to the following commands:
```console
# Generate CMakeToolchain.txt
mkdir -p Build/x86_64
cp Toolchain/CMake/GNUToolchain.txt.in Build/x86_64/CMakeToolchain.txt
sed -i 's/@SERENITY_ARCH@/x86_64/g' Build/x86_64/CMakeToolchain.txt
sed -i 's/@SERENITY_SOURCE_DIR@/'"$PWD"'/g' Build/x86_64/CMakeToolchain.txt
sed -i 's/@SERENITY_BUILD_DIR@/'"$PWD"'\/Build\/x86_64/g' Build/x86_64/CMakeToolchain.txt
# Configure and install Lagom
cmake -GNinja -S Meta/Lagom -B Build/lagom -DCMAKE_INSTALL_PREFIX=${PWD}/Build/lagom-install
ninja -C Build/lagom install
# Configure and install Serenity, pointing it to Lagom's install prefix
cmake -GNinja -B Build/x86_64 -DCMAKE_PREFIX_PATH=${PWD}/Build/lagom-install -DSERENITY_ARCH=x86_64 -DCMAKE_TOOLCHAIN_FILE=${PWD}/Build/x86_64/CMakeToolchain.txt
ninja -C Build/x86_64 install
```
Directing future `ninja` or `cmake --build` invocations to the `superbuild-<arch>` directory ensures that any headers or cpp files shared between the
host and target builds will be rebuilt, and the new host tools and libraries will be staged to the lagom-install directory. This is where the superbuild
differs from manually entering the commands above, it establishes a dependency between the install stage of lagom and the configure/build stages of Serenity.
The main limitation of the SuperBuild is that any non-option CMake cache variables such as component configuration or debug flag settings must be done
after a build has started. That is, the CMakeCache.txt for the Serenity and Lagom builds is not created until the SuperBuild build starts and reaches the
proper stage for the build in question. For more information on the CMake cache see the [CMake Cache Manipulation](#cmake-cache-manipulation) section above.
The debug flags might be manipulated after a build per the following commands:
```console
# Initial build, generate binary directories for both child builds
$ cmake -GNinja -S Meta/CMake/Superbuild -B Build/superbuild-x86_64 -DSERENITY_ARCH=x86_64 -DSERENITY_TOOLCHAIN=GNU
$ cmake --build Build/superbuild-x86_64
# Turn on process debug and don't build the browser for the Serenity build
$ cmake -B Build/x86_64 -DPROCESS_DEBUG=ON -DBUILD_BROWSER=OFF
$ ninja -C Build/x86_64 install
# Build host tests in Lagom build
$ cmake -S Meta/Lagom -B Build/lagom -DBUILD_LAGOM=ON
$ ninja -C Build/lagom install
```
## Component Configuration ## Component Configuration
For selecting which components of the system to build and install, a helper program, `ConfigureComponents` is available. For selecting which components of the system to build and install, a helper program, `ConfigureComponents` is available.
@ -178,58 +77,11 @@ This will prompt you which build type you want to use and allows you to customiz
## Tests ## Tests
For information on running host and target tests, see [Running Tests](RunningTests.md). The documentation there explains the difference between host tests run with Lagom and 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.
target tests run on SerenityOS. It also contains useful information for debugging CI test failures.
## Running SerenityOS with VirtualBox and VMware
Outside of QEMU, Serenity will run on VirtualBox and VMware. If you're curious, see how to [install Serenity on VirtualBox](VirtualBox.md) or [install Serenity on VMware](VMware.md).
## Running SerenityOS on bare metal
Bare curious users may even consider sourcing suitable hardware to [install Serenity on a physical PC.](BareMetalInstallation.md)
## Filesystem performance on Windows
If you're using the native Windows QEMU binary, QEMU is not able to access the ext4 root partition
of the WSL2 installation without going via the 9P network file share. The root of your WSL2 distro will begin at the
network path `\\wsl$\{distro-name}`.
Alternatively, you may prefer to copy `Build/_disk_image` and `Build/Kernel/Kernel` to a native Windows partition (e.g.
`/mnt/c`) before running `ninja run`, in which case `SERENITY_DISK_IMAGE` will be a regular Windows path (e.g.
`'D:\serenity\_disk_image'`).
## Clang-based toolchain
SerenityOS can also be built with the [Clang](https://en.wikipedia.org/wiki/Clang) compiler instead of GCC. This is
useful for stopping us from relying on compiler-specific behavior, and the built-in static analyzer helps us catch more
bugs. Code compiled with both of these toolchains works identically in most cases, with the limitation that ports
can't be built with Clang yet.
To build the Clang-based toolchain, run `BuildClang.sh` from the `Toolchain` directory. The script will build a Clang
toolchain that is capable of building applications for the build host and serenity.
**Warning:** While the build script is running, your computer may slow down extremely or even lock up for short
intervals. This generally happens if you have more CPU cores than free RAM in gigabytes. To fix this, limit the number
of parallel compile tasks be setting the `MAKEJOBS` environment variable to a number less than your CPU core count.
Once the build script finishes, you can use it to compile SerenityOS. Either set the `SERENITY_TOOLCHAIN` build
option to `Clang` as shown [above](#cmake-build-options), or pass `Clang` as the TOOLCHAIN option to
`Meta/serenity.sh`, for example: `Meta/serenity.sh run x86_64 Clang`.
### Serenity-aware clang tools
Building the clang-based toolchain also builds libTooling-based tools such as clang-format, clang-tidy and (optionally)
clangd that are aware of SerenityOS as a valid target. These tools will be installed into ``Toolchain/Local/clang/bin`` by
the script. Pointing your editor's plugins to the custom-built clang tools and a ``compile_commands.json`` from a clang build
of Serenity can enable richer error reporting than the tools that are installed for the build host.
To enable building clangd as part of the clang toolchain, set ``CLANG_ENABLE_CLANGD`` environment variable to ``ON``, then run ``Toolchain/BuildClang.sh``.
## Clang-format updates ## Clang-format updates
Some OS distributions don't ship bleeding-edge clang-format binaries. Below are 3 options to acquire an updated clang-format tool, in order of preference: Some OS distributions don't ship bleeding-edge clang-format binaries. Below are 2 options to acquire an updated clang-format tool, in order of preference:
1) If you have a Debian-based (apt-based) distribution, use the [LLVM apt repositories](https://apt.llvm.org) to install the latest release of clang-format. 1) If you have a Debian-based (apt-based) distribution, use the [LLVM apt repositories](https://apt.llvm.org) to install the latest release of clang-format.
2) Compile the SerenityOS-patched LLVM from source using ``Toolchain/BuildClang.sh`` as described above and use the compiled ``Toolchain/Local/clang/bin/clang-format`` binary in your editor and terminal. The meta-lint-ci pre-commit hook will automatically pick up the Toolchain clang-format binary. 2) Compile LLVM from source as described in the LLVM documentation [here](https://llvm.org/docs/GettingStarted.html#compiling-the-llvm-suite-source-code).
3) Compile LLVM from source as described in the LLVM documentation [here](https://llvm.org/docs/GettingStarted.html#compiling-the-llvm-suite-source-code).

View file

@ -12,7 +12,7 @@ Ensure that your system has the following tools available:
## Opening the project ## Opening the project
After opening the ``serenity`` directory in Android Studio (NOT the Ladybird/Android directory!) After opening the ``ladybird`` directory in Android Studio (NOT the Ladybird/Android directory!)
there should be a pop-up in the bottom left indicating that an Android Gradle project was detected there should be a pop-up in the bottom left indicating that an Android Gradle project was detected
in ``Ladybird/Android``. in ``Ladybird/Android``.

View file

@ -78,7 +78,7 @@ We separate CSS rules by their cascade origin. The two origins we're concerned w
The cascade origin determines the processing order for rules. The "user-agent" style is the least important, so it gets processed first. Then author style is added on top of that. The cascade origin determines the processing order for rules. The "user-agent" style is the least important, so it gets processed first. Then author style is added on top of that.
Note: the user-agent style is a built-in CSS style sheet that lives in the LibWeb source code [here](https://github.com/SerenityOS/serenity/blob/master/Userland/Libraries/LibWeb/CSS/Default.css). Note: the user-agent style is a built-in CSS style sheet that lives in the LibWeb source code [here](https://github.com/LadybirdWebBrowser/ladybird/blob/master/Userland/Libraries/LibWeb/CSS/Default.css).
The end product of style computation is a fully populated StyleProperties object. It has a StyleValue for each CSS::PropertyID. In spec parlance, these are the *computed* values. (Note that these are not the same as you get from `getComputedStyle()`, that API returns the *resolved* values.) The end product of style computation is a fully populated StyleProperties object. It has a StyleValue for each CSS::PropertyID. In spec parlance, these are the *computed* values. (Note that these are not the same as you get from `getComputedStyle()`, that API returns the *resolved* values.)

View file

@ -1,144 +0,0 @@
# SerenityOS build instructions
## Prerequisites
Make sure you have all the dependencies installed:
### Debian / Ubuntu
```console
sudo apt install build-essential cmake curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs ninja-build qemu-system-gui qemu-system-x86 qemu-utils ccache rsync unzip texinfo libssl-dev
```
Optional: `fuse2fs` for [building images without root](https://github.com/SerenityOS/serenity/pull/11224).
#### GCC 13 or Clang 17
A host compiler that supports C++23 features is required for building host tools, the newer the better. Tested versions include gcc-13 and clang-17.
On Ubuntu gcc-13 is available in the repositories of 24.04 (Noble) and later.
If you are running an older version, you will either need to upgrade, or find an alternative installation source
(i.e. from the [ubuntu-toolchain-r/test PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test)).
Next, update your local package information from this repository:
```console
sudo apt update
```
Now on Ubuntu or Debian you can install gcc-13 with apt like this:
```console
sudo apt install gcc-13 g++-13
```
#### QEMU 6.2 or later
Version 6.2 of QEMU is available in Ubuntu 22.04. On earlier versions of Ubuntu,
you can build the recommended version of QEMU as provided by the toolchain by running
`Toolchain/BuildQemu.sh`.
Note that you might need additional dev packages in order to build QEMU on your machine:
```console
sudo apt install libgtk-3-dev libpixman-1-dev libsdl2-dev libslirp-dev libspice-server-dev
```
#### CMake version 3.25.0 or later
Serenity-specific patches were upstreamed to CMake in major version 3.25. To avoid carrying
patches to CMake, the minimum required CMake to build Serenity is set to that version.
If more patches are upstreamed to CMake, the minimum will be bumped again once that version releases.
To accommodate distributions that do not ship bleeding-edge CMake versions, the build scripts will
attempt to build CMake from source if the version on your path is older than 3.25.x.
If you have previously compiled SerenityOS with an older or distribution-provided version of CMake,
you will need to manually remove the CMakeCache.txt files, as these files reference the older CMake version and path.
```console
rm Build/*/CMakeCache.txt
```
### Windows
If you're on Windows you can use WSL2 to build SerenityOS. Please have a look at the [Windows guide](BuildInstructionsWindows.md)
for details.
### Arch Linux / Manjaro
```console
sudo pacman -S --needed base-devel cmake curl mpfr libmpc gmp e2fsprogs ninja qemu-desktop qemu-system-aarch64 ccache rsync unzip
```
Optional: `fuse2fs` for [building images without root](https://github.com/SerenityOS/serenity/pull/11224).
### SerenityOS
The following ports need to be installed:
```console
bash cmake curl e2fsprogs gawk genext2fs git ninja patch python3 qemu rsync
```
Additionally, for building using LLVM, install the `llvm` port.
For building using GCC, install the `gcc`, `gmp` and `mpc` ports.
Due to not-yet-finished POSIX shell support in `Shell`, a symlink from `/bin/sh` to `/usr/local/bin/bash` is required.
This is best achieved by adding `ln -sf /usr/local/bin/bash mnt/bin/sh` to your [customization script](AdvancedBuildInstructions.md#customizing-the-disk-image).
### Other systems
There is also documentation for installing the build prerequisites for some less commonly used systems:
* [Other Linux distributions and \*NIX systems](BuildInstructionsOther.md)
* [macOS](BuildInstructionsMacOS.md)
## Build
Run the following command to build and run SerenityOS:
```console
Meta/serenity.sh run
```
This will compile all of SerenityOS and install the built files into the `Build/x86_64/Root` directory inside your Git
repository. It will also build a disk image and start SerenityOS using QEMU.
The first time this command is executed, it will also download some required database files from the internet and build
the SerenityOS cross-compiler toolchain. These steps only have to be done once, so the next build will go much faster.
When we update to a newer compiler, you might be prompted to re-build the toolchain; see the [troubleshooting guide](Troubleshooting.md#the-toolchain-is-outdated)
for what to do when this happens.
If, during build, an error like `fusermount: failed to open /etc/mtab: No such file or directory` appears, you have installed `fuse2fs` but your system does not provide the mtab symlink for various reasons. Simply create this symlink with `ln -sv /proc/self/mounts /etc/mtab`.
Note that the `anon` user is able to become `root` without a password by default, as a development convenience.
To prevent this, remove `anon` from the `wheel` group and he will no longer be able to run `/bin/su`.
By default the `anon` user account's password is: `foo`
If you want to test whether your code changes compile without running the VM you can use
`Meta/serenity.sh build`. The `serenity.sh` script also provides a number of other commands. Run the script without
arguments for a list.
## Ports
To add a package from the ports collection to Serenity, for example curl, change into the `Ports/curl` directory and
run `./package.sh`. The source code for the package will be downloaded and the package will be built. The next time you
start Serenity, `curl` will be available.
Ports might also have additional dependencies. Most prominently, you may need:
`autoconf`, `automake`, `bison`, `flex`, `gettext`, `gperf`, `help2man`, `imagemagick` (specifically "convert"),
`libgpg-error-dev`, `libtool`, `lzip`, `meson`, `nasm` (or another assembler), `python3-packaging`, `qt6-base-dev`,
`rename`, `zip`.
For select ports you might need slightly more exotic dependencies such as:
- `file` (version 5.44 exactly, for file)
- `libpython3-dev` (most prominently for boost)
- `lua` (for luarocks)
- `openjdk-17-jdk` (to compile OpenJDK)
- `rake` (to build mruby).
You may also need a symlink from "/usr/bin/python" to "/usr/bin/python3"; some ports depend on "python" existing, most notably ninja.
## More information
At this point you should have a fully functioning VM for SerenityOS. The [advanced build instructions guide](AdvancedBuildInstructions.md)
has more information for some less commonly used features of the build system.

View file

@ -94,7 +94,7 @@ Or, download a version of Gradle >= 8.0.0, and run the ``gradlew`` program in ``
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 serenity.sh script:
```bash ```bash
# From /path/to/serenity # From /path/to/ladybird
./Meta/serenity.sh run lagom ladybird ./Meta/serenity.sh run lagom ladybird
./Meta/serenity.sh gdb lagom ladybird ./Meta/serenity.sh gdb lagom ladybird
``` ```
@ -108,7 +108,7 @@ The Qt chrome is available on platforms where it is not the default as well (exc
Qt chrome, install the Qt dependencies for your platform, and enable the Qt chrome via CMake: Qt chrome, install the Qt dependencies for your platform, and enable the Qt chrome via CMake:
```bash ```bash
# From /path/to/serenity # From /path/to/ladybird
cmake -S Meta/Lagom -B Build/lagom -DENABLE_QT=ON cmake -S Meta/Lagom -B Build/lagom -DENABLE_QT=ON
``` ```
@ -129,7 +129,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 serenity/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 serenity.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

View file

@ -111,6 +111,6 @@ Depending on whether you understand the internals of the compiler, this may or m
Clang also supports `-ftime-report`, but I have not tested the output for it. Clang also supports `-ftime-report`, but I have not tested the output for it.
To add the flag, edit the `CMakeLists.txt` in the serenity root directory, and add `add_compile_options(-ftime-report)` to the list of compile options that start around line 220. To add the flag, edit the `CMakeLists.txt` in the ladybird root directory, and add `add_compile_options(-ftime-report)` to the list of compile options that start around line 220.
Additionally, you can add `-ftime-report-details` too, which again I have not tested. Additionally, you can add `-ftime-report-details` too, which again I have not tested.

View file

@ -2,7 +2,7 @@
CLion can integrate with CMake to provide code comprehension features. CLion can integrate with CMake to provide code comprehension features.
After opening the `serenity` 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/x86_64`)
@ -77,15 +77,15 @@ Finally, to quickly switch between the two different contexts, simply click the
### Toolchain ### Toolchain
If the serenity directory is on the WSL filesystem you need to configure the CLion toolchain to be WSL. If the ladybird directory is on the WSL filesystem you need to configure the CLion toolchain to be WSL.
To set that up go to `File->Settings->Build, Execution, Deployment->Toolchains` and click on the `+` icon, then select WSL. In `Toolset` select the distribution you have the serenity directory on. To set that up go to `File->Settings->Build, Execution, Deployment->Toolchains` and click on the `+` icon, then select WSL. In `Toolset` select the distribution you have the ladybird directory on.
### Terminal ### Terminal
It is possible to set the embedded terminal in CLion to the one that your WSL distribution provides. It is possible to set the embedded terminal in CLion to the one that your WSL distribution provides.
This way you can build and run serenity without leaving the IDE. This way you can build and run ladybird without leaving the IDE.
Note that following will only help if you don't use an X-window server to access qemu. Note that following will only help if you don't use an X-window server to access qemu.
It is possible to install qemu natively on Windows and allow WSL to use it instead of installing qemu first on (wsl) linux and then use X server to launch serenity inside of it. It is possible to install qemu natively on Windows and allow WSL to use it instead of installing qemu first on (wsl) linux and then use X server to launch ladybird inside of it.
Check the updated manual [here](BuildInstructionsWindows.md). Check the updated manual [here](BuildInstructionsWindows.md).
- Locate the terminal emulator for your linux distribution. - Locate the terminal emulator for your linux distribution.
@ -100,4 +100,4 @@ Copy `absolute/path/to/ubuntu2004.exe`.
- Close CLion and restart. - Close CLion and restart.
The default IDE terminal should now be changed to WSL, and now you can run `CLion/run.sh`. The default IDE terminal should now be changed to WSL, and now you can run `CLion/run.sh`.
You may also want to copy `serenity/Meta/CLion/run.sh` to your project directory and run it from there, so that you don't have to fight with git every time you modify the script. You may also want to copy `ladybird/Meta/CLion/run.sh` to your project directory and run it from there, so that you don't have to fight with git every time you modify the script.

View file

@ -4,7 +4,7 @@ For low-level styling (spaces, parentheses, brace placement, etc), all code shou
**Important: Make sure you use `clang-format` version 18 or later!** **Important: Make sure you use `clang-format` version 18 or later!**
This document describes the coding style used for C++ code in the Serenity Operating System project. All new code should conform to this style. This document describes the coding style used for C++ code in the Ladybird Browser project. All new code should conform to this style.
We'll definitely be tweaking and amending this over time, so let's consider it a living document. :) We'll definitely be tweaking and amending this over time, so let's consider it a living document. :)

View file

@ -13,15 +13,15 @@ CompileFlags:
Add: Add:
- "-D__serenity__" - "-D__serenity__"
- "-UNO_TLS" - "-UNO_TLS"
- "-I/path/to/serenity/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"
- "-I/path/to/serenity/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/13.1.0/x86_64-pc-serenity" - "-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
MissingIncludes: None MissingIncludes: None
``` ```
You will need to change `/path/to/serenity` 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/serenity.sh run` or similar) at least once for this
@ -48,7 +48,7 @@ There are a few different ways to specify which clangd to use:
- By default, without configuration `lsp-mode` will try to find and use your system `clangd`. This is the easiest solution, but your system clangd might be out of date. - By default, without configuration `lsp-mode` will try to find and use your system `clangd`. This is the easiest solution, but your system clangd might be out of date.
- You can manually specify any `clangd` binary with `lsp-clangd-binary-path`, as shown in the use-package example above. - You can manually specify any `clangd` binary with `lsp-clangd-binary-path`, as shown in the use-package example above.
- You can have `lsp-mode` manage your `clangd` installation with emacs' `lsp-install-server`. This will install a `clangd` binary for you. - You can have `lsp-mode` manage your `clangd` installation with emacs' `lsp-install-server`. This will install a `clangd` binary for you.
- You can build the LLVM toolchain, including `clangd`, from Serenity's repository. This is an advanced option that is not currently documented. - You can build the LLVM toolchain, including `clangd`, from Ladybird's repository. This is an advanced option that is not currently documented.
### clang-format ### clang-format

View file

@ -1,47 +1,19 @@
# Frequently Asked Questions about SerenityOS # Frequently Asked Questions about Ladybird
## Will SerenityOS support `$THING`? ## Will Ladybird support `$THING`?
Maybe. Maybe not. There is no plan. Eventually, probably, if there's a Web Spec for it!
## When will you implement `$THING`? ## When will you implement `$THING`?
Maybe someday. Maybe never. If you want to see something happen, you can do it yourself! Maybe someday. Maybe never. If you want to see something happen, you can do it yourself!
## Where are the ISO images?
There are no ISO images. This project does not cater to non-technical users.
## Well, how do I run this thing then? ## Well, how do I run this thing then?
Simple, my friend! Just refer to the [build instructions](BuildInstructions.md). Simple, my friend! Just refer to the [build instructions](BuildInstructionsLadybird.md).
## I did a `git pull` and now the build is broken! What do I do? ## I did a `git pull` and now the build is broken! What do I do?
If it builds on CI, it should build for you too. You may need to rebuild the toolchain. If that doesn't help, try it with a clean repo. If it builds on CI, it should build for you too. You may need to rebuild the toolchain. If that doesn't help, try it with a clean repo.
If you can't figure out what to do, ask in the `#build-problems` channel on Discord. If you can't figure out what to do, ask in the `#build-problems` channel on Discord.
## Why don't you use `$LIBRARY` instead of implementing `$FEATURE` yourself?
The SerenityOS project tries to maximize hackability, accountability, and fun(!) by implementing everything ourselves.
## Does SerenityOS have a package manager?
In short, no, SerenityOS does not have a "Linux-style" package manager with pre-built software.
More specifically, SerenityOS does not have a package manager that allows you to download pre-built binary images software. The project uses a monorepo approach, meaning that all software is built in the same style and using the same tools. Additionally, the SerenityOS ABI, such as library symbols or syscall interfaces, have absolutely no stability guarantee and should be expected to change at any moment. (You can expect the POSIX C library API to remain relatively stable.) There is no reason to have a binary package manager because of this.
The supported method to use third-party software is by compiling ports that can be found in the [Ports directory](../Ports). A port is a piece of software that can optionally be installed, might not have been built by us, but supports running on SerenityOS. They act quite similarly to packages, each coming with their own install script. The significant difference is that ports are always built from source.
Currently when running the system in a virtual machine, ports should be cross compiled on the host, and added to the file system image before booting. It is possible to compile ports on SerenityOS itself, which requires quite a bit of manual work. At the moment, this is not a recommended or actively supported workflow. In the future, this process *may* be supported more easily with the `pkg` tool. If you are interested in contributing in this regard, take a look at the #package-manager channel on Discord.
In regards to SerenityOS components themselves, it is possible to [exclude some of them](./AdvancedBuildInstructions.md#component-configuration) from the build at compile time.
## Why is there an MP3 implementation in SerenityOS if MP3 is protected by patents?
*This section is informational; we are not lawyers and this is not legal advice. Consult a qualified lawyer if you have legal questions regarding your use of SerenityOS software.*
MP3 was indeed originally protected by patents, preventing certain uses of the format. All MP3 patents, however, have expired since at least 2017, depending on where a specific patent was registered. Therefore, we believe it to be completely legal to implement MP3 as 2-clause BSD licensed software without acquiring patent licenses.
*However*, this does not apply to many other multimedia formats, such as the popular H.264 (AVC) and H.265 (HEVC) video codecs or the JPEG 2000 image format. As long as there is any reason to believe that a format is covered by patents, there will not be an implementation in the SerenityOS monorepo, as we believe this to be incompatible with the BSD 2-clause license in general. *However however*, third-party ports with differing licenses can provide implementations for these formats, such as ffmpeg. Depending on your situation and/or use case, using this third-party software might not be legal (for example, see the [ffmpeg information on the same topic](https://ffmpeg.org/legal.html)). Everything regarding the legal situation of the SerenityOS code is handled by [our license](../LICENSE), everything regarding the legal situation of third-party code is handled by the license of the particular software.

View file

@ -1,5 +1,5 @@
# Helix Configuration # Helix Configuration
Helix comes with support for `clangd` and `clang-format` out of the box! However, a small bit of configuration is needed for it to work correctly with SerenityOS. Helix comes with support for `clangd` and `clang-format` out of the box! However, a small bit of configuration is needed for it to work correctly with Ladybird.
The following `.clangd` should be placed in the project root: The following `.clangd` should be placed in the project root:
```yaml ```yaml

View file

@ -1,73 +0,0 @@
# SerenityOS-related pages across the web
This is a roughly categorized list of pages relating to SerenityOS and its subprojects across the web. Many of these pages are "unofficial" in that some single person created them and/or maintains them independently; but we only list pages here that are widely recognized and of good quality. If you want your Serenity related page to be listed, just create a pull request adding it and we can discuss.
## General
- **[serenityos.org](https://serenityos.org)**
- [Manpages](https://man.serenityos.org/)
- Birthday Posts
- [1st](https://www.serenityos.org/happy/1st/)
- [2nd](https://www.serenityos.org/happy/2nd/)
- [3rd](https://www.serenityos.org/happy/3rd/)
- [4th](https://www.serenityos.org/happy/4th/)
- [Emoji](https://emoji.serenityos.org/)
- [Try it out Online!](https://copy.sh/v86/?profile=serenity) (This is an old i686 build which will never be updated as [i686 support is removed](https://github.com/SerenityOS/serenity/pull/15467).)
- [SerenityOS on English Wikipedia](https://en.wikipedia.org/wiki/SerenityOS). This page also links to the SerenityOS articles in many other languages.
## Development
- [GitHub Organization](https://github.com/SerenityOS) and [GitHub Repositories](https://github.com/orgs/SerenityOS/repositories)
- [Changelog](https://changelog.serenityos.org/)
- [Issues Found by OSS-Fuzz Continuous Fuzzing](https://bugs.chromium.org/p/oss-fuzz/issues/list?q=label:Proj-serenity)
- [LibJS website](https://serenityos.github.io/libjs-website/)
- [Try LibJS Online!](https://serenityos.github.io/libjs-website/repl/)
- [Compiler Explorer](https://serenity.godbolt.org/): Select "Lagom trunk" under "Libraries" and add the compiler option `-std=c++23`
## Related Projects
- [LibFont.js](https://macdue.github.io/LibFont.js/)
## Social
- [Discord Server](https://discord.gg/serenityos)
- [serenityos.social](https://serenityos.social/), unofficial Mastodon instance run by [networkException](https://serenityos.social/@networkexception) and [Linus Groh](https://serenityos.social/@linusg)
- [Map of Developers and Users](https://usermap.serenityos.org/)
- YouTube Channels
- [Andreas Kling](https://www.youtube.com/@awesomekling)
- [Linus Groh](https://www.youtube.com/@linusgroh)
- [kleines Filmröllchen](https://www.youtube.com/@kleinesfilmroellchen)
- [davidot](https://www.youtube.com/@davidot4475)
- Personal Blogs
- [Andreas Kling](https://awesomekling.github.io/)
- [Linus Groh](https://linus.dev/posts/)
- [Andrew Kaster](https://adkaster.github.io/)
- [Jesse Buhagiar](https://quaker762.github.io/)
- [Sam Atkins](https://atkinssj.github.io/)
## Statistics and Lists
- [Ports](https://ports.serenityos.net/)
- [:^) Tracker](https://happy-serenityos.linus.dev/)
- [FIXMEs](https://benwiederhake.github.io/serenity-fixmes/)
- [Flamegraph Distribution](https://benwiederhake.github.io/serenity-fixmes/flamegraph.html)
- [Lines of Code vs. Commits](https://github.com/alimpfard/random-serenity-statistics#random-serenityos-statistics)
- [CSS Conformance](https://css.tobyase.de/)
- [Fonts](https://fonts.serenityos.net/)
- [Emoji Table](https://emoji.serenityos.net/)
- [Emoji Statistics](https://emoji.serenityos.net/chart.emoji.serenityos)
- [Flags](https://flags.serenityos.net/)
- [test262](https://serenityos.github.io/libjs-website/test262/) (JavaScript Spec Tests)
- [Wasm Spec Tests](https://serenityos.github.io/libjs-website/wasm/)
- [Test Performance](https://github.com/alimpfard/random-serenity-statistics/tree/main/view/benchmarks/x86_64)
- [serenityos.social Statistics](https://grafana.serenityos.social/public)
## Miscellaneous
- [Merch](https://store.serenityos.org)
- [Yaksplained](https://yaksplained.org/)
- [serenityos.net](https://serenityos.net), [Xexxa](https://github.com/xexxa)'s site for various pages listed here
- [Font Wishlist & Useful Links for Font Developers](https://serenityos.net/~xexxa/)
- [Emoji Wall Of Awesome](https://emoji.serenityos.net/wall-of-awesome)
- [Unofficial Wiki](https://wiki.serenityos.net/)
- [Spinning Ladyball Shadertoy](https://www.shadertoy.com/view/7lVXWd)

View file

@ -181,9 +181,9 @@ nmap <silent>gs :CocCommand clangd.switchSourceHeader vsplit<CR>
> **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/serenity.sh rebuild`.
Link `ln -s /path/to/serenity/Build/x86_64/compile_commands.json /path/to/serenity/compile_commands.json`. Link `ln -s /path/to/ladybird/Build/x86_64/compile_commands.json /path/to/ladybird/compile_commands.json`.
Create `/path/to/serenity/.clangd` (replace `/path/to/serenity` Create `/path/to/ladybird/.clangd` (replace `/path/to/ladybird`
with your SerenityOS directory) with content of the clangd section in the with your SerenityOS directory) with content of the clangd section in the
[VSCodeConfiguration.md](./VSCodeConfiguration.md). [VSCodeConfiguration.md](./VSCodeConfiguration.md).

View file

@ -1,4 +1,4 @@
# SerenityOS Patterns # Coding Patterns
## Introduction ## Introduction
@ -39,26 +39,6 @@ ErrorOr<NonnullRefPtr<Bitmap>> Bitmap::create_shareable(BitmapFormat format, Int
} }
``` ```
Example from the Kernel:
```cpp
#include <AK/Try.h>
... snip ...
ErrorOr<Region*> AddressSpace::allocate_region(VirtualRange const& range, StringView name, int prot, AllocationStrategy strategy)
{
VERIFY(range.is_valid());
OwnPtr<KString> region_name;
if (!name.is_null())
region_name = TRY(KString::try_create(name));
auto vmobject = TRY(AnonymousVMObject::try_create_with_size(range.size(), strategy));
auto region = TRY(Region::try_create_user_accessible(range, move(vmobject), 0, move(region_name), prot_to_region_access_flags(prot), Region::Cacheable::Yes, false));
TRY(region->map(page_directory()));
return add_region(move(region));
}
```
Note: Our `TRY(...)` macro functions similarly to the `?` [operator in rust](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator). Note: Our `TRY(...)` macro functions similarly to the `?` [operator in rust](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator).
## `MUST(...)` Error Handling ## `MUST(...)` Error Handling

View file

@ -7,7 +7,7 @@ First, make sure you have a working toolchain and can build and run SerenityOS.
* Install [Qt Creator](https://www.qt.io/offline-installers). You don't need the entire Qt setup, just click 'Qt Creator' on the left side, and install that. * Install [Qt Creator](https://www.qt.io/offline-installers). You don't need the entire Qt setup, just click 'Qt Creator' on the left side, and install that.
* Open Qt Creator, select `File -> New File or Project...` * Open Qt Creator, select `File -> New File or Project...`
* Select `Import Existing Project` * Select `Import Existing Project`
* Give it a name (some tools assume lower-case `serenity`), and navigate to the root of your SerenityOS project checkout. Click Next. * Give it a name (some tools assume lower-case `ladybird`), and navigate to the root of your SerenityOS project checkout. Click Next.
* Wait for the file list to generate. This can take a minute or two! * Wait for the file list to generate. This can take a minute or two!
* Ignore the file list, we will overwrite it later. Click Next. * Ignore the file list, we will overwrite it later. Click Next.
* Set `Add to version control` to `<None>`. Click Finish. * Set `Add to version control` to `<None>`. Click Finish.

View file

@ -1,4 +1,4 @@
# SerenityOS Documentation # Ladybird Documentation
Serenity development moves quickly, so some of these might be out of date. Please let us know if something here is wrong, or submit a PR with any additions or corrections! If you have any questions that are not answered here or in the [FAQ](FAQ.md), you are welcome to ask on [Discord](../README.md#get-in-touch-and-participate). Serenity development moves quickly, so some of these might be out of date. Please let us know if something here is wrong, or submit a PR with any additions or corrections! If you have any questions that are not answered here or in the [FAQ](FAQ.md), you are welcome to ask on [Discord](../README.md#get-in-touch-and-participate).

View file

@ -54,7 +54,7 @@ tar xzf ./actions-runner-linux-x64-X.X.X.tar.gz
``` ```
### Link the runner to the repository ### Link the runner to the repository
```shell ```shell
./config.sh --url https://github.com/SerenityOS/serenity --token INSERT_SECRET_TOKEN_HERE ./config.sh --url https://github.com/LadybirdWebBrowser/ladybird --token INSERT_SECRET_TOKEN_HERE
``` ```
### Configure the runner to protect against malicious PRs by adding the following line to .env: ### Configure the runner to protect against malicious PRs by adding the following line to .env:
```shell ```shell

View file

@ -2,18 +2,13 @@
In case of an error, you might find an answer of how to deal it here. In case of an error, you might find an answer of how to deal it here.
## Building SerenityOS ## Building Ladybird
### 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.16 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).
### QEMU is missing or is outdated
Ensure your [QEMU](https://www.qemu.org/) version is >= 5 with `qemu-system-i386 -version`. Otherwise,
install it. You can also build it using the `Toolchain/BuildQemu.sh` script.
### The toolchain is outdated ### The toolchain is outdated
We strive to use the latest compilers and build tools to ensure the best developer experience; so every We strive to use the latest compilers and build tools to ensure the best developer experience; so every
@ -63,47 +58,3 @@ MinProtocol = TLSv1.2
CipherString = DEFAULT@SECLEVEL=1 CipherString = DEFAULT@SECLEVEL=1
Options = UnsafeLegacyRenegotiation Options = UnsafeLegacyRenegotiation
``` ```
## Running SerenityOS
### The VM is really slow
On Linux, QEMU is significantly faster if it's able to use KVM. The run script will automatically enable KVM
if `/dev/kvm` exists and is readable+writable by the current user. On Windows, ensure that you have
WHPX acceleration enabled.
### Slow boot on HiDPI systems
On some Windows systems running with >100% scaling, the booting phase of Serenity might slow to a crawl. Changing the
zoom settings of the QEMU window will speed up the emulation, but you'll have to squint harder to read the smaller display.
The default display backend (`SERENITY_QEMU_DISPLAY_BACKEND=sdl,gl=off`) does _not_ have this problem. If you're
running into this problem, make sure you haven't changed the QEMU display backend.
A quick workaround is opening the properties of the QEMU executable at `C:\Program Files\qemu\qemu-system-x86_64.exe`, and
in the Compatibility tab changing the DPI settings to force the scaling to be performed by the System, by changing the
setting at at the bottom of the window. The QEMU window will now render at normal size while retaining acceptable emulation speeds.
This is being tracked as issue [#7657](https://github.com/SerenityOS/serenity/issues/7657).
### Boot fails with "Error: Kernel Image too big for memory slot. Halting!"
This means the kernel is too large again. Contact us on the discord server or open a GitHub Issue about it.
You might want to revert latest changes in tree to see if that solves the problem temporarily.
### Boot fails with "Your computer does not support long mode (64-bit mode). Halting!"
Either your machine (if you try to boot on bare metal) is very old, thus it's not supporting x86_64
extensions, or you try to use VirtualBox without using a x64 virtualization mode or you try to use
`qemu-system-i386` which doesn't support x86_64 extensions too.
### Boot fails with "Your computer does not support PAE. Halting!"
- If booting on bare metal, your CPU is too old to boot Serenity.
- If you're using VirtualBox, you need to enable PAE/NX. Check the instructions [here.](VirtualBox.md)
- If you're using QEMU, the [CPU model configuration](https://qemu-project.gitlab.io/qemu/system/qemu-cpu-models.html) is not exposing PAE.
### Boot fails with "KVM doesn't support guest debugging"
- Update your host kernel to at least version `5.10`. This is the oldest kernel which properly supports the required KVM capability `KVM_CAP_SET_GUEST_DEBUG` (see corresponding [kernel commit](https://github.com/torvalds/linux/commit/b9b2782cd5)).
- Make sure that your distro has the qemu debug feature actually enabled (the corresponding check is [here](https://gitlab.com/qemu-project/qemu/-/blob/222059a0fccf4af3be776fe35a5ea2d6a68f9a0b/accel/kvm/kvm-all.c#L2540)).
- Or, disable KVM debugging by setting this env var when running serenity: `SERENITY_DISABLE_GDB_SOCKET=1`

View file

@ -1,46 +0,0 @@
# Ladybird
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).
The Browser UI has a cross-platform GUI in Qt6 and a macOS-specific GUI in AppKit.
Ladybird aims to be a standards-compliant, independent web browser with no third-party dependencies.
Currently, the only dependencies are UI frameworks like Qt6 and AppKit, and low-level platform-specific
libraries like PulseAudio, CoreAudio and OpenGL.
> [!IMPORTANT]
> Ladybird is in a pre-alpha state, and only suitable for use by developers
## Features
The Ladybird browser application uses a multiprocess architecture with a main UI process, several WebContent renderer processes,
an ImageDecoder process, a RequestServer process, and a SQLServer process for holding cookies.
Image decoding and network connections are done out of process to be more robust against malicious content.
Each tab has its own renderer process, which is sandboxed from the rest of the system.
All the core library support components are developed in the serenity monorepo:
- LibWeb: Web Rendering Engine
- LibJS: JavaScript Engine
- LibWasm: WebAssembly implementation
- LibCrypto/LibTLS: Cryptography primitives and Transport Layer Security (rather than OpenSSL)
- LibHTTP: HTTP/1.1 client
- LibGfx: 2D Graphics Library, Image Decoding and Rendering (rather than skia)
- LibArchive: Archive file format support (rather than libarchive, zlib)
- LibUnicode, LibLocale: Unicode and Locale support (rather than libicu)
- LibAudio, LibVideo: Audio and Video playback (rather than libav, ffmpeg)
- LibCore: Event Loop, OS Abstraction layer
- LibIPC: Inter-Process Communication
- ... and more!
## Building and Development
See [build instructions](../Documentation/BuildInstructionsLadybird.md) for information on how to build Ladybird.
See [CONTRIBUTING.md](../CONTRIBUTING.md) for information on how to contribute to Ladybird.
## More Information
For more information about the history of Ladybird, see [this blog post](https://awesomekling.github.io/Ladybird-a-new-cross-platform-browser-project/).
The official website for Ladybird is [ladybird.dev](https://ladybird.dev).

View file

@ -22,9 +22,9 @@ FROM fedora:39 AS serenity-build
WORKDIR /home WORKDIR /home
RUN dnf install -y clang cmake git-core ninja-build RUN dnf install -y clang cmake git-core ninja-build
RUN git clone --depth=1 https://github.com/SerenityOS/serenity RUN git clone --depth=1 https://github.com/LadybirdWebBrowser/ladybird
RUN cd serenity/Meta/Lagom && ./BuildFuzzers.sh RUN cd ladybird/Meta/Lagom && ./BuildFuzzers.sh
FROM fedora:39 AS fuzzilli-build FROM fedora:39 AS fuzzilli-build

View file

@ -91,7 +91,7 @@ on the second stage of the CMake build, or in your environment.
There are many quirky files that exercise a lot of interesting edge cases. There are many quirky files that exercise a lot of interesting edge cases.
We should probably keep track of them, somewhere. We should probably keep track of them, somewhere.
We have a [bmp suite and a jpg suite and several others](https://github.com/SerenityOS/serenity/tree/master/Base/res/html/misc). We have a [bmp suite and a jpg suite and several others](https://github.com/LadybirdWebBrowser/ladybird/tree/master/Base/res/html/misc).
They are GPL'ed, and therefore not quite as compatible with the rest of Serenity. They are GPL'ed, and therefore not quite as compatible with the rest of Serenity.
That's probably not a problem, but keeping "our" testcases separate from those GPL'ed suits sounds like a good idea. That's probably not a problem, but keeping "our" testcases separate from those GPL'ed suits sounds like a good idea.

166
README.md
View file

@ -1,157 +1,53 @@
# SerenityOS and Ladybird # Ladybird
SerenityOS is a graphical Unix-like operating system for x86-64 computers. [Ladybird](https://ladybird.dev) is a truly independent web browser, using a novel engine based on web standards.
Ladybird is a cross-platform independent web browser built from SerenityOS components. > [!IMPORTANT]
> Ladybird is in a pre-alpha state, and only suitable for use by developers
>
[![GitHub Actions Status](https://github.com/SerenityOS/serenity/workflows/Build,%20lint,%20and%20test/badge.svg)](https://github.com/SerenityOS/serenity/actions?query=workflow%3A"Build%2C%20lint%2C%20and%20test") ## Features
[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/serenity.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:serenity)
[![Discord](https://img.shields.io/discord/830522505605283862.svg?logo=discord&logoColor=white&logoWidth=20&labelColor=7289DA&label=Discord&color=17cf48)](https://discord.gg/serenityos)
[FAQ](Documentation/FAQ.md) | [Documentation](#how-do-i-read-the-documentation) | [Build Instructions](#how-do-i-build-and-run-this) We aim to build a complete, usable browser for the modern web.
## About SerenityOS Ladybird uses a multi-process architecture with a main UI process, several WebContent renderer processes,
an ImageDecoder process, a RequestServer process, and a SQLServer process for holding cookies.
SerenityOS is a love letter to '90s user interfaces with a custom Unix-like core. It flatters with sincerity by stealing beautiful ideas from various other systems. Image decoding and network connections are done out of process to be more robust against malicious content.
Each tab has its own renderer process, which is sandboxed from the rest of the system.
Roughly speaking, the goal is a marriage between the aesthetic of late-1990s productivity software and the power-user accessibility of late-2000s \*nix. This is a system by us, for us, based on the things we like. At the moment, many core library support components are inherited from SerenityOS:
You can watch videos of the system being developed on YouTube: - LibWeb: Web rendering engine
- LibJS: JavaScript engine
* [Andreas Kling's channel](https://youtube.com/andreaskling) - LibWasm: WebAssembly implementation
* [Linus Groh's channel](https://youtube.com/linusgroh) - LibCrypto/LibTLS: Cryptography primitives and Transport Layer Security
* [kleines Filmröllchen's channel](https://www.youtube.com/c/kleinesfilmroellchen) - LibHTTP: HTTP/1.1 client
- LibGfx: 2D Graphics Library, Image Decoding and Rendering
## About Ladybird - LibArchive: Archive file format support
- LibUnicode, LibLocale: Unicode and locale support
Ladybird is a cross-platform independent web browser built from SerenityOS components. It is a separate project from SerenityOS, but it uses the SerenityOS build system and shares much of the same code. - LibAudio, LibVideo: Audio and video playback
All the browser UI code lives in the Serenity repository under the `Ladybird` directory. The SerenityOS LibGUI port of Ladybird lives in the `Userland/Applications/Browser` directory. - LibCore: Event loop, OS abstraction layer
All the implementation details are in the `Userland/Libraries` and `Userland/Services` directories. - LibIPC: Inter-process communication
See the Ladybird [README.md](Ladybird/README.md) for more information.
## SerenityOS Screenshot
![Screenshot as of c03b788.png](Meta/Screenshots/screenshot-c03b788.png)
## SerenityOS Features
* Modern x86 64-bit kernel with pre-emptive multi-threading
* [Browser](Userland/Applications/Browser/) with JavaScript, WebAssembly, and more (check the spec compliance for [JS](https://serenityos.github.io/libjs-website/test262/), [CSS](https://css.tobyase.de/), and [Wasm](https://serenityos.github.io/libjs-website/wasm/))
* Security features (hardware protections, limited userland capabilities, W^X memory, `pledge` & `unveil`, (K)ASLR, OOM-resistance, web-content isolation, state-of-the-art TLS algorithms, ...)
* [System services](Userland/Services/) (WindowServer, LoginServer, AudioServer, WebServer, RequestServer, CrashServer, ...) and modern IPC
* Good POSIX compatibility ([LibC](Userland/Libraries/LibC/), Shell, syscalls, signals, pseudoterminals, filesystem notifications, standard Unix [utilities](Userland/Utilities/), ...)
* POSIX-like virtual file systems (/proc, /dev, /sys, /tmp, ...) and ext2 file system
* Network stack and applications with support for IPv4, TCP, UDP; DNS, HTTP, Gemini, IMAP, NTP
* Profiling, debugging and other development tools (Kernel-supported profiling, CrashReporter, interactive GUI playground, HexEditor, HackStudio IDE for C++ and more)
* [Libraries](Userland/Libraries/) for everything from cryptography to OpenGL, audio, JavaScript, GUI, playing chess, ...
* Support for many common and uncommon file formats (PNG, JPEG, GIF, MP3, WAV, FLAC, ZIP, TAR, PDF, QOI, Gemini, ...)
* Unified style and design philosophy, flexible theming system, [custom (bitmap and vector) fonts](https://fonts.serenityos.net/font-family)
* [Games](Userland/Games/) (Solitaire, Minesweeper, 2048, chess, Conway's Game of Life, ...) and [demos](Userland/Demos/) (CatDog, Starfield, Eyes, mandelbrot set, WidgetGallery, ...)
* Every-day GUI programs and utilities (Spreadsheet with JavaScript, TextEditor, Terminal, PixelPaint, various multimedia viewers and players, Mail, Assistant, Calculator, ...)
... and all of the above are right in this repository, no extra dependencies, built from-scratch by us :^)
Additionally, there are [over three hundred ports of popular open-source software](Ports/AvailablePorts.md), including games, compilers, Unix tools, multimedia apps and more.
## How do I read the documentation?
Man pages are available online at [man.serenityos.org](https://man.serenityos.org). These pages are generated from the Markdown source files in [`Base/usr/share/man`](https://github.com/SerenityOS/serenity/tree/master/Base/usr/share/man) and updated automatically.
When running SerenityOS you can use `man` for the terminal interface, or `help` for the GUI.
Code-related documentation can be found in the [documentation](Documentation/) folder.
## How do I build and run this? ## How do I build and run this?
See the [SerenityOS build instructions](https://github.com/SerenityOS/serenity/blob/master/Documentation/BuildInstructions.md) or the [Ladybird build instructions](Documentation/BuildInstructionsLadybird.md). See [build instructions](Documentation/BuildInstructionsLadybird.md) for information on how to build Ladybird.
The build system supports a cross-compilation build of SerenityOS from Linux, macOS, Windows (with WSL2) and many other *Nixes. Ladybird runs on Linux, macOS, Windows (with WSL2), and many other \*Nixes.
The default build system commands will launch a QEMU instance running the OS with hardware or software virtualization
enabled as supported.
Ladybird runs on the same platforms that can be the host for a cross build of SerenityOS and on SerenityOS itself. ## How do I read the documentation?
Code-related documentation can be found in the [documentation](Documentation/) folder.
## Get in touch and participate! ## Get in touch and participate!
Join our Discord server: [SerenityOS Discord](https://discord.gg/serenityos) Join [our Discord server](https://discord.gg/nvfjVJ4Svh) to participate in development discussion.
Before opening an issue, please see the [issue policy](https://github.com/SerenityOS/serenity/blob/master/CONTRIBUTING.md#issue-policy). Before opening an issue, please see the [issue policy](CONTRIBUTING.md#issue-policy).
A general guide for contributing can be found in [`CONTRIBUTING.md`](CONTRIBUTING.md). A general guide for contributing can be found in [`CONTRIBUTING.md`](CONTRIBUTING.md).
## Authors
* **Andreas Kling** - [awesomekling](https://twitter.com/awesomekling) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/awesomekling)
* **Robin Burchell** - [rburchell](https://github.com/rburchell)
* **Conrad Pankoff** - [deoxxa](https://github.com/deoxxa)
* **Sergey Bugaev** - [bugaevc](https://github.com/bugaevc)
* **Liav A** - [supercomputer7](https://github.com/supercomputer7)
* **Linus Groh** - [linusg](https://github.com/linusg) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/linusg)
* **Ali Mohammad Pur** - [alimpfard](https://github.com/alimpfard)
* **Shannon Booth** - [shannonbooth](https://github.com/shannonbooth)
* **Hüseyin ASLITÜRK** - [asliturk](https://github.com/asliturk)
* **Matthew Olsson** - [mattco98](https://github.com/mattco98)
* **Nico Weber** - [nico](https://github.com/nico)
* **Brian Gianforcaro** - [bgianfo](https://github.com/bgianfo)
* **Ben Wiederhake** - [BenWiederhake](https://github.com/BenWiederhake)
* **Tom** - [tomuta](https://github.com/tomuta)
* **Paul Scharnofske** - [asynts](https://github.com/asynts)
* **Itamar Shenhar** - [itamar8910](https://github.com/itamar8910)
* **Luke Wilde** - [Lubrsi](https://github.com/Lubrsi)
* **Brendan Coles** - [bcoles](https://github.com/bcoles)
* **Andrew Kaster** - [ADKaster](https://github.com/ADKaster) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ADKaster)
* **thankyouverycool** - [thankyouverycool](https://github.com/thankyouverycool)
* **Idan Horowitz** - [IdanHo](https://github.com/IdanHo)
* **Gunnar Beutner** - [gunnarbeutner](https://github.com/gunnarbeutner)
* **Tim Flynn** - [trflynn89](https://github.com/trflynn89)
* **Jean-Baptiste Boric** - [boricj](https://github.com/boricj)
* **Stephan Unverwerth** - [sunverwerth](https://github.com/sunverwerth)
* **Max Wipfli** - [MaxWipfli](https://github.com/MaxWipfli)
* **Daniel Bertalan** - [BertalanD](https://github.com/BertalanD)
* **Jelle Raaijmakers** - [GMTA](https://github.com/GMTA)
* **Sam Atkins** - [AtkinsSJ](https://github.com/AtkinsSJ) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/AtkinsSJ)
* **Tobias Christiansen** - [TobyAsE](https://github.com/TobyAsE)
* **Lenny Maiorani** - [ldm5180](https://github.com/ldm5180)
* **sin-ack** - [sin-ack](https://github.com/sin-ack)
* **Jesse Buhagiar** - [Quaker762](https://github.com/Quaker762)
* **Peter Elliott** - [Petelliott](https://github.com/Petelliott)
* **Karol Kosek** - [krkk](https://github.com/krkk)
* **Mustafa Quraish** - [mustafaquraish](https://github.com/mustafaquraish)
* **David Tuin** - [davidot](https://github.com/davidot)
* **Leon Albrecht** - [Hendiadyoin1](https://github.com/Hendiadyoin1)
* **Tim Schumacher** - [timschumi](https://github.com/timschumi)
* **Marcus Nilsson** - [metmo](https://github.com/metmo)
* **Gegga Thor** - [Xexxa](https://github.com/Xexxa) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/Xexxa)
* **kleines Filmröllchen** - [kleinesfilmroellchen](https://github.com/kleinesfilmroellchen) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/kleinesfilmroellchen)
* **Kenneth Myhra** - [kennethmyhra](https://github.com/kennethmyhra)
* **Maciej** - [sppmacd](https://github.com/sppmacd)
* **Sahan Fernando** - [ccapitalK](https://github.com/ccapitalK)
* **Benjamin Maxwell** - [MacDue](https://github.com/MacDue)
* **Dennis Esternon** - [djwisdom](https://github.com/djwisdom) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/djwisdom)
* **frhun** - [frhun](https://github.com/frhun)
* **networkException** - [networkException](https://github.com/networkException) [![GitHub Sponsors](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/networkException)
* **Brandon Jordan** - [electrikmilk](https://github.com/electrikmilk)
* **Lucas Chollet** - [LucasChollet](https://github.com/LucasChollet)
* **Timon Kruiper** - [FireFox317](https://github.com/FireFox317)
* **Martin Falisse** - [martinfalisse](https://github.com/martinfalisse)
* **Gregory Bertilson** - [Zaggy1024](https://github.com/Zaggy1024)
* **Erik Wouters** - [EWouters](https://github.com/EWouters)
* **Rodrigo Tobar** - [rtobar](https://github.com/rtobar)
* **Alexander Kalenik** - [kalenikaliaksandr](https://github.com/kalenikaliaksandr)
* **Tim Ledbetter** - [tcl3](https://github.com/tcl3)
* **Steffen T. Larssen** - [stelar7](https://github.com/stelar7)
* **Andi Gallo** - [axgallo](https://github.com/axgallo)
* **Simon Wanner** - [skyrising](https://github.com/skyrising)
* **FalseHonesty** - [FalseHonesty](https://github.com/FalseHonesty)
* **Bastiaan van der Plaat** - [bplaat](https://github.com/bplaat)
* **Dan Klishch** - [DanShaders](https://github.com/DanShaders)
* **Julian Offenhäuser** - [janso3](https://github.com/janso3)
* **Sönke Holz** - [spholz](https://github.com/spholz)
* **implicitfield** - [implicitfield](https://github.com/implicitfield)
And many more! [See here](https://github.com/SerenityOS/serenity/graphs/contributors) for a full contributor list. The people listed above have landed more than 100 commits in the project. :^)
## License ## License
SerenityOS is licensed under a 2-clause BSD license. Ladybird is licensed under a 2-clause BSD license.

View file

@ -1,5 +1,3 @@
# Security Policy # Security Policy
SerenityOS is a hobby operating system developed by volunteers. It is unreleased software still in early development, and so bugs and vulnerabilities can be safely disclosed publicly. If you find an issue, we would prefer if you report it as a [GitHub issue](https://github.com/SerenityOS/serenity/issues/new). If your issue was found using a fuzzer, please check [oss-fuzz](https://bugs.chromium.org/p/oss-fuzz/issues/list?q=label:Proj-serenity) first to see if it has already been recorded. Ladybird is unreleased software still in early development, and so bugs and vulnerabilities can be safely disclosed publicly. If you find an issue, we would prefer if you report it as a [GitHub issue](https://github.com/LadybirdWebBrowser/ladybird/issues/new). If your issue was found using a fuzzer, please check [oss-fuzz](https://bugs.chromium.org/p/oss-fuzz/issues/list?q=label:Proj-serenity) first to see if it has already been recorded.
We run a modest [Bug Bounty Program](https://serenityos.org/bounty/) to reward people who find certain kinds of exploits in the system. See that link for details, and to claim your reward. :^)