diff --git a/docs/contributing/index.md b/docs/contributing/index.md index e6cc043c8..7b92015fc 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -82,7 +82,7 @@ The `./docs/commands`, `./docs/functions`, and `./docs/configuration` folders ar ```{.bash .copy} ./scripts/generate-docs.sh ``` -to update the documentation. Commit these changes in a separate commit. +to update the documentation. You need to have a supported version of GDB *and* [LLDB installed](setup-pwndbg-dev.md#running-with-lldb) for this to work. Commit these changes in a separate commit. If you forget to do that the CI will detect a discrepency between the documentation and source code (using the `./scripts/verify-docs.sh` script, which you may also invoke yourself) and prevent your PR from being merged (until you push new changes, re-running the CI). diff --git a/docs/contributing/setup-pwndbg-dev.md b/docs/contributing/setup-pwndbg-dev.md index 1c7b9f199..7252c0e91 100644 --- a/docs/contributing/setup-pwndbg-dev.md +++ b/docs/contributing/setup-pwndbg-dev.md @@ -65,6 +65,9 @@ After installing Pwndbg like described above, there are a few ways to set up the ``` but you can also use the [docker container](#development-from-docker) or [develop using nix](#development-using-nix). +!!! note + For a proper development environment you must be able to run Pwndbg with both GDB and LLDB, otherwise you won't be able to use some important development features (like doc generation). + ### Development from docker You can create a Docker image with everything already installed for you. You can use docker compose ```{.bash .copy} diff --git a/scripts/_docs/extract-all-docs.sh b/scripts/_docs/extract-all-docs.sh index 18c667dd3..4940b6010 100755 --- a/scripts/_docs/extract-all-docs.sh +++ b/scripts/_docs/extract-all-docs.sh @@ -1,5 +1,23 @@ #!/usr/bin/env bash +# Check that supported LLDB is installed. +if ! command -v lldb &> /dev/null; then + echo "Cannot reliably extract information from sources because LLDB" + echo "is not installed. See installation instructions:" + echo "https://pwndbg.re/pwndbg/dev/contributing/setup-pwndbg-dev/#running-with-lldb" + exit 3 +else + version=$(lldb --version | awk '{print $3}') + major_version=${version%%.*} + + if [ "$major_version" -lt 19 ]; then + echo "Cannot reliably extract information from sources because your LLDB" + echo "version (${version}) is too old. Supported is LLDB >= 19. See installation instructions:" + echo "https://pwndbg.re/pwndbg/dev/contributing/setup-pwndbg-dev/#running-with-lldb" + exit 4 + fi +fi + source "$(dirname "$0")/../common.sh" cd $PWNDBG_ABS_PATH diff --git a/setup-dev.sh b/setup-dev.sh index ab0d65363..fd56c7823 100755 --- a/setup-dev.sh +++ b/setup-dev.sh @@ -349,3 +349,25 @@ if linux; then configure_venv fi fi + +# LLDB is needed for docs generation. Tell the user +# if they don't have it installed or if it's an unsupported version. +if ! command -v lldb &> /dev/null; then + echo "WARNING: lldb not found in PATH, some functionality" + echo "(e.g. docs generation) will not be available." + echo "See installation instructions:" + echo "https://pwndbg.re/pwndbg/dev/contributing/setup-pwndbg-dev/#running-with-lldb" +else + version=$(lldb --version | awk '{print $3}') + major_version=${version%%.*} + + if [ "$major_version" -ge 19 ]; then + echo "Supported LLDB installed. All good!" + else + echo "WARNING: lldb found in PATH, but the version is too old." + echo "Installed: ${version}. Supported: >= 19." + echo "Some functionality (e.g. docs generation) will not be available." + echo "See installation instructions:" + echo "https://pwndbg.re/pwndbg/dev/contributing/setup-pwndbg-dev/#running-with-lldb" + fi +fi