beenull/ladybird
1
0
Fork 0
mirror of https://github.com/LadybirdBrowser/ladybird.git synced 2024-11-21 23:20:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6
ladybird/Documentation/Troubleshooting.md

66 lines
3.7 KiB
Markdown
Raw Normal View History

Documentation: Add simple troubleshooting guide In this guide, we explain two boot errors that can occur and what can be done to solve them.
2021-07-07 17:50:32 +00:00
# Troubleshooting
In case of an error, you might find an answer of how to deal it here.
Documentation: Reorganize the build documentation
2021-07-09 22:53:28 +00:00
## Building SerenityOS
Documentation: Add simple troubleshooting guide In this guide, we explain two boot errors that can occur and what can be done to solve them.
2021-07-07 17:50:32 +00:00
Documentation: Reorganize the build documentation
2021-07-09 22:53:28 +00:00
### 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
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.
### GCC is missing or is outdated
Everywhere: Require version >= 12 for GCC host compiler So far we've gotten away with using GCC 11 for Lagom and to compile the toolchain, but via #15795 we discovered a compiler bug that has been fixed in the latest version but would error the build with CI's GCC 11. Time for an upgrade :^) We already use ubuntu-22.04 images in most places, so this is pretty straightforward. The only exception is Idan's self-hosted runner, which uses Ubuntu Focal. LibJS should build fine with GCC 11, still.
2022-10-25 19:28:09 +00:00
Ensure your gcc version is >= 12 with `gcc --version`. Otherwise, install it. If your gcc binary is not
Documentation: Reorganize the build documentation
2021-07-09 22:53:28 +00:00
called `gcc` you have to specify the names of your C and C++ compiler when you run cmake, e.g.
Everywhere: Require version >= 12 for GCC host compiler So far we've gotten away with using GCC 11 for Lagom and to compile the toolchain, but via #15795 we discovered a compiler bug that has been fixed in the latest version but would error the build with CI's GCC 11. Time for an upgrade :^) We already use ubuntu-22.04 images in most places, so this is pretty straightforward. The only exception is Idan's self-hosted runner, which uses Ubuntu Focal. LibJS should build fine with GCC 11, still.
2022-10-25 19:28:09 +00:00
`cmake ../.. -GNinja -DCMAKE_C_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12`.
Documentation: Reorganize the build documentation
2021-07-09 22:53:28 +00:00
## 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.
Documentation: Move the QEMU troubleshooting section This is no longer relevant for most users because due to an unrelated change to Meta/run.sh the default display backend is now SDL which does not exhibit this problem.
2021-07-10 12:49:05 +00:00
### 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).
Documentation: Reorganize the build documentation
2021-07-09 22:53:28 +00:00
### Boot fails with "Error: Kernel Image too big for memory slot. Halting!"
Documentation: Add simple troubleshooting guide In this guide, we explain two boot errors that can occur and what can be done to solve them.
2021-07-07 17:50:32 +00:00
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.
Documentation: Reorganize the build documentation
2021-07-09 22:53:28 +00:00
### 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.
Documentation: Add simple troubleshooting guide In this guide, we explain two boot errors that can occur and what can be done to solve them.
2021-07-07 17:50:32 +00:00
Documentation: Reorganize the build documentation
2021-07-09 22:53:28 +00:00
### Boot fails with "Your computer does not support PAE. Halting!"
Kernel: Stop booting and print if PAE is not supported by the processor We currently require PAE and not having it causes us to crash. This turns that crash into an error message.
2021-07-08 20:19:30 +00:00
- 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.
Documentation: Add troubleshooting note regarding KVM GDB
2022-12-30 12:00:27 +00:00
### 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`
Reference in a new issue Copy permalink