ladybird/Documentation/Troubleshooting.md

# Troubleshooting

In case of an error, you might find an answer of how to deal it here.

## Building Ladybird

### CMake fails to configure the build because it's outdated

Ensure your CMake version is >= 3.25 with `cmake --version`. If your system doesn't provide a suitable
version of CMake, you can download a binary release from the [CMake website](https://cmake.org/download).

### GCC is missing or is outdated

Ensure your gcc version is >= 13 with `gcc --version`. Otherwise, install it. If your gcc binary is not
called `gcc` you have to specify the names of your C and C++ compiler when you run cmake, e.g.
`cmake ../.. -GNinja -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13`.

### Legacy renegotiation is disabled

Ensure your `/etc/ssl/openssl.cnf` file has the following options:

```console
[openssl_init]
ssl_conf = ssl_sect

[ssl_sect]
system_default = system_default_sect

[system_default_sect]
MinProtocol = TLSv1.2
CipherString = DEFAULT@SECLEVEL=1
Options = UnsafeLegacyRenegotiation
```

#### “Targets may link only to libraries. CMake is dropping the item” message (when building with the Qt chrome on macOS)

When building with the Qt chrome on macOS, you may encounter the following message:

> CMake Warning at /opt/homebrew/Cellar/qt/6.7.0_1/lib/cmake/Qt6/FindWrapOpenGL.cmake:48 (target_link_libraries):
> Target "ladybird" requests linking to directory "/usr/X11R6/lib". Targets
> may link only to libraries. CMake is dropping the item.

…followed by 14-line stack trace, the top of which is this:

> Toolchain/Tarballs/vcpkg/scripts/buildsystems/vcpkg.cmake:859 (_find_package)

…and all of it shown in bright yellow, making you think it must be important and something must need to be fixed. But that’s not the case. Instead, despite that, you’ll be able to build successfully with the Qt chrome.
-												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.
-												Meta: Update Documentation and CI for repo move

											
										
										
											2024-05-30 21:06:21 +00:00
+								## Building Ladybird
-												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
-												Documentation: Remove references to serenity.sh and its build configs

Build/lagom only now.

											
										
										
											2024-05-31 23:27:20 +00:00
+								Ensure your CMake version is >= 3.25 with `cmake --version`. If your system doesn't provide a suitable
-												Documentation: Reorganize the build documentation

											
										
										
											2021-07-09 22:53:28 +00:00
+								version of CMake, you can download a binary release from the [CMake website](https://cmake.org/download).
 								### GCC is missing or is outdated
-												CI: Bump Lagom CI builds to gcc-13 and clang-18

This includes Lagom Tools for Serenity builds, and the Lagom builds on
Azure.

											
										
										
											2024-02-05 10:45:43 +00:00
+								Ensure your gcc version is >= 13 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.
-												CI: Bump Lagom CI builds to gcc-13 and clang-18

This includes Lagom Tools for Serenity builds, and the Lagom builds on
Azure.

											
										
										
											2024-02-05 10:45:43 +00:00
+								`cmake ../.. -GNinja -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13`.
-												Documentation: Reorganize the build documentation

											
										
										
											2021-07-09 22:53:28 +00:00
-												Documentation: Add instructions to disable OpenSSL legacy renegotiation

In distributions with newer versions of OpenSSL, when you run
Meta/serenity.sh rebuild-toolchain you'll get curl: (35)
error:0A000152:SSL routines::unsafe legacy renegotiation
disabled. This is because OpenSSL was compiled with legacy
renegotiation disabled by default. I've added instructions
to Documentation/BuildInstructions.md to solve this issue.

											
										
										
											2023-08-07 16:48:29 +00:00
+								### Legacy renegotiation is disabled
 								Ensure your `/etc/ssl/openssl.cnf` file has the following options:
 								```console
 								[openssl_init]
 								ssl_conf = ssl_sect
 								[ssl_sect]
 								system_default = system_default_sect
 								[system_default_sect]
 								MinProtocol = TLSv1.2
 								CipherString = DEFAULT@SECLEVEL=1
 								Options = UnsafeLegacyRenegotiation
 								```
-												Documentation: Add guidance on X11R6 linking warning message

											
										
										
											2024-07-27 00:37:15 +00:00
 								#### “Targets may link only to libraries. CMake is dropping the item” message (when building with the Qt chrome on macOS)
 								When building with the Qt chrome on macOS, you may encounter the following message:
 								> CMake Warning at /opt/homebrew/Cellar/qt/6.7.0_1/lib/cmake/Qt6/FindWrapOpenGL.cmake:48 (target_link_libraries):
 								> Target "ladybird" requests linking to directory "/usr/X11R6/lib". Targets
 								> may link only to libraries. CMake is dropping the item.
 								…followed by 14-line stack trace, the top of which is this:
 								> Toolchain/Tarballs/vcpkg/scripts/buildsystems/vcpkg.cmake:859 (_find_package)
 								…and all of it shown in bright yellow, making you think it must be important and something must need to be fixed. But that’s not the case. Instead, despite that, you’ll be able to build successfully with the Qt chrome.