Skip to content

Clarify installation instructions: building from source, and guidance for packagers #4780

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rouault merged 3 commits into from
May 31, 2026
+23 −11
Merged

Clarify installation instructions: building from source, and guidance for packagers #4780

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5d7ba63
install.rst: Say that the file covers building from source
gdt May 21, 2026
41a76fd
install: Shorten autotools history
gdt May 21, 2026
de15ed8
install: Explain dependencies more
gdt May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 23 additions & 11 deletions docs/source/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,19 @@
Installation
================================================================================

These pages describe how to install PROJ on your computer without compiling it
yourself. Below are guides for installing on Windows, Linux and Mac OS X. This
is a good place to get started if this is your first time using PROJ. More
advanced users may want to compile the software themselves.
These pages describe how to install PROJ on your computer, covering a
variety of operating systems.

There is a section for using package management systems. If PROJ is
available for a package management system you already use, and you
wish to run the release of PROJ offered by that system (usually that's
fine), this is is the easiest path.

There is a second section for building from source. This section can
be followed if there is no binary package available for your
operating and CPU combination or if you wish to install a different
version, including the tip of master in git, or pending fixes. It is
of course also useful to those creating packages.

Installation from package management systems
################################################################################
Expand Down Expand Up @@ -130,14 +139,17 @@ Compilation and installation from source code

The classic way of installing PROJ is via the source code distribution. The
most recent version is available from the :ref:`download page<current_release>`.
Alternatively, one can also check out the master branch or any other revision from GitHub.

The following guides show how to compile and install the software using CMake.

.. note::
Note that some sections below presume an unpacked release tarball, and
some say to use a git checkout.

Support for Autotools was maintained until PROJ 8.2 (see :ref:`RFC7`).
PROJ 9.0 and later releases only support builds using CMake.
As of PROJ 9.0, the only build system is CMake. (The last release
with Autotools was 8.2.)
Comment on lines -138 to +148
Copy link
Copy Markdown
Member

@kbevers kbevers May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just discard this entirely? Autotools is not relevant in the context of current PROJ versions. This just sounds like we're making excuses. In reality the original wording is probably a remnant of a time when we didn't offer versioned docs. If you somehow find yourself with the source code of an old PROJ you can go back to a previous version of the docs.

Copy link
Copy Markdown
Contributor Author

@gdt gdt May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't really matter to be, but one point is that I was trying to edit somewhat lightly. I don't see it as making excuses so much as being clear about withdrawal timing.

The second point is that people may be coming to a new release from various old releases, perhaps with build scripts, and the build system switch is a big deal -- but it can be described in one brief sentence. README points to unversioned docs, which change, so for any given release, the online version might be from the future. I see the benefit of unconfusing someone as larger than the harm for someone who doesn't care to skip quickly over a sentence.

Happy to drop the remark about autoconf/8.2, if the three of you have a combined opinion.


Packagers and others with similar policy constraints should note that
an outdated vendored copy of nlohmann/json may be used and that
GoogleTest may be downloaded at build time (details below).

Requirements
--------------------------------------------------------------------------------
Expand All @@ -151,15 +163,15 @@ Build requirements
- SQLite3 >= 3.11: headers and library for target architecture, and sqlite3 executable for build architecture
- libtiff >= 4.0 (optional but recommended to enable reading of grid formats based on GeoTIFF. Only basic TIFF support is required; optional features like WebP or ZStd are not needed.)
- curl >= 7.29.0 (optional but recommended to support automatic downloading of remote grid files during runtime, allowing PROJ to fetch required transformation data on demand.)
- JSON for Modern C++ (nlohmann/json) >= 3.7.0
- JSON for Modern C++ (nlohmann/json) >= 3.7.0 (a vendored 3.9.1 will be used if not found; use `-DNLOHMANN_JSON_ORIGIN=EXTERNAL` to prevent this)


.. _test_requirements:

Test requirements
+++++++++++++++++

These are only required if testing is built (see :option:`BUILD_TESTING`, default ON)
If :option:`BUILD_TESTING` is ON (the default), test programs will be be compiled at build time, and the following additional dependencies are required:

- GoogleTest (GTest) >= 1.8.1; if not found and :option:`TESTING_USE_NETWORK` is ON, then version 1.15.2 is fetched from GitHub and locally installed
- Python >= 3.7
Expand Down
Loading