Doc: Consolidate info on build dependencies and processes
- CONTRIBUTING.md is replaced with a link to the "contributing" section of the docs - Information on build requirements is consolidated in "development/dev_environment.rst" - Build instructions are moved from "build_hints.rst" to "development/building_from_source.rst" - Basic information on running tests is added to "development/testing.rst" - Git usage is moved from CONTRIBUTING.md to "development/dev_practices.rst" - Basic information on building docs is added to "development/dev_documentationrst." The style guide is moved from "contributing" to this location.
This commit is contained in:
Daniel Baston
parent
5327c149f5
commit
ef5aaef7f4
233
CONTRIBUTING.md
233
CONTRIBUTING.md
|
|
@ -1,232 +1 @@
|
|||
# Setting development environment (Unix)
|
||||
|
||||
## Build SWIG
|
||||
|
||||
SWIG (https://swig.org/) is required to compile GDAL with other programming languages, such as Python.
|
||||
|
||||
> **Note**
|
||||
> SWIG version 4.0.2 is required.
|
||||
|
||||
Set the installation path:
|
||||
|
||||
```bash
|
||||
export SWIG_PREFIX=/path/to/install
|
||||
|
||||
```
|
||||
|
||||
Install SWIG from source:
|
||||
|
||||
```bash
|
||||
export SWIG_VERSION=4.0.2
|
||||
mkdir /tmp/swig/
|
||||
cd /tmp/swig/
|
||||
wget https://sourceforge.net/projects/swig/files/swig/swig-${SWIG_VERSION}/swig-${SWIG_VERSION}.tar.gz/download -O swig-${SWIG_VERSION}.tar.gz
|
||||
tar xf swig-${SWIG_VERSION}.tar.gz
|
||||
cd swig-${SWIG_VERSION}
|
||||
./configure --prefix=$SWIG_PREFIX
|
||||
make
|
||||
make install
|
||||
export PATH=$SWIG_PREFIX/bin:$PATH
|
||||
```
|
||||
|
||||
## Build GDAL: CMake
|
||||
|
||||
Install all required development packages: GNU make, g++, ...
|
||||
|
||||
Setup [Python Virtual environment](https://docs.python.org/3/library/venv.html):
|
||||
|
||||
> **Note**
|
||||
> Add the [Python_FIND_VIRTUALENV=ONLY](https://gdal.org/build_hints.html#cmdoption-arg-Python_FIND_VIRTUALENV) `cmake` option with a Python virtual environment.
|
||||
|
||||
```bash
|
||||
python -m venv gdal_venv
|
||||
. gdal_venv/bin/activate
|
||||
python -m pip install numpy
|
||||
```
|
||||
|
||||
Setup pre-commit:
|
||||
|
||||
```bash
|
||||
python -m pip install pre-commit
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
|
||||
Configure and build:
|
||||
|
||||
> **Note**
|
||||
> For a minimal build, add these options: `GDAL_BUILD_OPTIONAL_DRIVERS=OFF` `OGR_BUILD_OPTIONAL_DRIVERS=OFF`.
|
||||
> To enable specific drivers, add `GDAL_ENABLE_DRIVER_<driver_name>=ON` or `OGR_ENABLE_DRIVER_<driver_name>=ON`.
|
||||
> See [Selection of Drivers](https://gdal.org/build_hints.html#selection-of-drivers)
|
||||
> for more details.
|
||||
|
||||
```bash
|
||||
mkdir build
|
||||
cd build
|
||||
cmake .. -DSWIG_EXECUTABLE=$SWIG_PREFIX/bin/swig -DSWIG_REGENERATE_PYTHON=ON [options]
|
||||
cmake --build . -j$(nproc)
|
||||
```
|
||||
|
||||
Run command line utilities (without installing):
|
||||
```bash
|
||||
. ../scripts/setdevenv.sh
|
||||
gdalinfo --version
|
||||
```
|
||||
This will set the PATH, LD_LIBRARY_PATH/DY_LD_LIBRARY_PATH, GDAL_DATA and PYTHONPATH environment variables to point to the build artifacts.
|
||||
|
||||
Run autotest suite:
|
||||
```bash
|
||||
python -m pip install -r ../autotest/requirements.txt
|
||||
pytest autotest
|
||||
```
|
||||
|
||||
## Build GDAL: use Vagrant
|
||||
|
||||
Make sure the Vagrant binary is installed on your system.
|
||||
|
||||
Perform initial setup of the Vagrant GDAL virtual machine:
|
||||
```bash
|
||||
# VAGRANT_VM_CPU=number_of_cpus
|
||||
vagrant up
|
||||
```
|
||||
|
||||
And then to incrementally develop into it:
|
||||
```bash
|
||||
vagrant ssh
|
||||
ninja
|
||||
```
|
||||
|
||||
Note that the following directories on the host will be created (and can be
|
||||
removed if no longer needed the Vagrant environment):
|
||||
- ../apt-cache/ubuntu/jammy64: contains a cache of Ubuntu packages of the VM,
|
||||
to allow faster VM reconstruction
|
||||
- build_vagrant: CMake build directory
|
||||
- ccache_vagrant: CCache directory
|
||||
|
||||
## Build GDAL: Autotools
|
||||
|
||||
> **Note**
|
||||
> Only applies to GDAL 3.4 or earlier
|
||||
|
||||
Install all required development packages: GNU make, g++, ...
|
||||
|
||||
Build:
|
||||
|
||||
```bash
|
||||
./autogen.sh
|
||||
./configure --with-python [other options]
|
||||
make -j8 -s
|
||||
cd apps; make -s test_ogrsf; cd ..
|
||||
```
|
||||
|
||||
Run command line utilities (without installing):
|
||||
```bash
|
||||
. scripts/setdevenv.sh
|
||||
gdalinfo --version
|
||||
```
|
||||
|
||||
Run autotest suite:
|
||||
```bash
|
||||
cd autotest
|
||||
pip install -r requirements.txt
|
||||
pytest
|
||||
```
|
||||
|
||||
# Git workflows with GDAL
|
||||
|
||||
This is not a git tutorial or reference manual by any means. This just collects
|
||||
a few best practice for git usage for GDAL development.
|
||||
|
||||
## Commit message
|
||||
|
||||
Indicate a component name (eg a driver name), a short description and when
|
||||
relevant, a reference to a issue (with 'fixes #' if it actually fixes it)
|
||||
|
||||
```
|
||||
COMPONENT_NAME: fix bla bla (fixes #1234)
|
||||
|
||||
Details here...
|
||||
```
|
||||
|
||||
## Initiate your work repository
|
||||
|
||||
Fork OSGeo/gdal from github UI, and then
|
||||
```bash
|
||||
git clone https://github.com/OSGeo/gdal
|
||||
cd gdal
|
||||
git remote add my_user_name git@github.com:my_user_name/gdal.git
|
||||
```
|
||||
|
||||
## Updating your local master against upstream master
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
git fetch origin
|
||||
# Be careful: this will loose all local changes you might have done now
|
||||
git reset --hard origin/master
|
||||
```
|
||||
|
||||
## Working with a feature branch
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
# potentially update your local master against upstream, as described above
|
||||
git checkout -b my_new_feature_branch
|
||||
|
||||
# do work. For example:
|
||||
git add my_new_file
|
||||
git add my_modifid_message
|
||||
git rm old_file
|
||||
git commit -a
|
||||
|
||||
# you may need to resynchronize against master if you need some bugfix
|
||||
# or new capability that has been added since you created your branch
|
||||
git fetch origin
|
||||
git rebase origin/master
|
||||
|
||||
# At end of your work, make sure history is reasonable by folding non
|
||||
# significant commits into a consistent set
|
||||
git rebase -i master
|
||||
# use 'fixup' for example to merge several commits together,
|
||||
# and 'reword' to modify commit messages
|
||||
|
||||
# or alternatively, in case there is a big number of commits and marking
|
||||
# all them as 'fixup' is tedious
|
||||
git fetch origin
|
||||
git rebase origin/master
|
||||
git reset --soft origin/master
|
||||
git commit -a -m "Put here the synthetic commit message"
|
||||
|
||||
# push your branch
|
||||
git push my_user_name my_new_feature_branch
|
||||
From GitHub UI, issue a pull request
|
||||
```
|
||||
|
||||
If the pull request discussion or Travis-CI/AppVeyor checks require changes,
|
||||
commit locally and push. To get a reasonable history, you may need to
|
||||
```git rebase -i master```, in which case you will have to force-push your
|
||||
branch with ```git push -f my_user_name my_new_feature_branch```
|
||||
|
||||
|
||||
## Backporting bugfixes from master to a stable branch
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
With git log, identify the sha1sum of the commit you want to backport
|
||||
git checkout 2.2 # if you want to backport to 2.2
|
||||
git pull origin 2.2
|
||||
# git checkout -b branch_name # if you intend to submit the backport as a pull request
|
||||
git cherry-pick the_sha1_sum
|
||||
git push ...
|
||||
```
|
||||
If changes are needed, do them and ```git commit -a --amend```
|
||||
|
||||
|
||||
## Things you should NOT do
|
||||
|
||||
(For anyone with push rights to github.com/OSGeo/gdal) Never modify a commit or
|
||||
the history of anything that has been
|
||||
committed to https://github.com/OSGeo/gdal
|
||||
|
||||
Committing symbolic links is allowed only under the .github directory in order to
|
||||
avoid potential problems on Windows.
|
||||
Contributor information is provided at the GDAL [website](https://gdal.org/contributing).
|
||||
|
|
@ -1,136 +0,0 @@
|
|||
.. _developer_contribution:
|
||||
|
||||
======================================
|
||||
Developer Contributions to GDAL
|
||||
======================================
|
||||
|
||||
Install all required development packages: GNU make, g++, …
|
||||
|
||||
Build:
|
||||
|
||||
::
|
||||
|
||||
cd gdal
|
||||
./autogen.sh
|
||||
./configure [options]
|
||||
make -j8 -s
|
||||
cd apps; make -s test_ogrsf; cd ..
|
||||
|
||||
Run command line utilities (without installing):
|
||||
|
||||
::
|
||||
|
||||
. scripts/setdevenv.sh
|
||||
gdalinfo --version
|
||||
|
||||
Run autotest suite:
|
||||
|
||||
::
|
||||
|
||||
cd ../autotest
|
||||
pip install -r requirements.txt
|
||||
pytest
|
||||
|
||||
Git workflows with GDAL
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
This is not a git tutorial or reference manual by any means. This just
|
||||
collects a few best practice for git usage for GDAL development.
|
||||
|
||||
Commit message
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Indicate a component name (eg a driver name), a short description and
|
||||
when relevant, a reference to a issue (with ‘fixes #’ if it actually
|
||||
fixes it)
|
||||
|
||||
::
|
||||
|
||||
COMPONENT_NAME: fix bla bla (fixes #1234)
|
||||
|
||||
Details here...
|
||||
|
||||
Initiate your work repository
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Fork `OSGeo/GDAL <https://github.com/OSGeo/gdal>`__ from GitHub UI, and then
|
||||
|
||||
::
|
||||
|
||||
git clone https://github.com/OSGeo/gdal
|
||||
cd gdal
|
||||
git remote add my_user_name https://github.com/my_user_name/gdal.git
|
||||
|
||||
Updating your local master against upstream master
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
::
|
||||
|
||||
git checkout master
|
||||
git fetch origin
|
||||
# Be careful: this will loose all local changes you might have done now
|
||||
git reset --hard origin/master
|
||||
|
||||
Working with a feature branch
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
::
|
||||
|
||||
git checkout master
|
||||
(potentially update your local master against upstream, as described above)
|
||||
git checkout -b my_new_feature_branch
|
||||
|
||||
# do work. For example:
|
||||
git add my_new_file
|
||||
git add my_modifid_message
|
||||
git rm old_file
|
||||
git commit -a
|
||||
|
||||
# you may need to resynchronize against master if you need some bugfix
|
||||
# or new capability that has been added since you created your branch
|
||||
git fetch origin
|
||||
git rebase origin/master
|
||||
|
||||
# At end of your work, make sure history is reasonable by folding non
|
||||
# significant commits into a consistent set
|
||||
git rebase -i master (use 'fixup' for example to merge several commits together,
|
||||
and 'reword' to modify commit messages)
|
||||
|
||||
# or alternatively, in case there is a big number of commits and marking
|
||||
# all them as 'fixup' is tedious
|
||||
git fetch origin
|
||||
git rebase origin/master
|
||||
git reset --soft origin/master
|
||||
git commit -a -m "Put here the synthetic commit message"
|
||||
|
||||
# push your branch
|
||||
git push my_user_name my_new_feature_branch
|
||||
From GitHub UI, issue a pull request
|
||||
|
||||
If the pull request discussion or CI checks require
|
||||
changes, commit locally and push. To get a reasonable history, you may
|
||||
need to ``git rebase -i master``, in which case you will have to
|
||||
force-push your branch with
|
||||
``git push -f my_user_name my_new_feature_branch``
|
||||
|
||||
Backporting bugfixes from master to a stable branch
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
::
|
||||
|
||||
git checkout master
|
||||
With git log, identify the sha1sum of the commit you want to backport
|
||||
git checkout 2.2 (if you want to backport to 2.2)
|
||||
git pull origin 2.2
|
||||
(git checkout -b branch_name: if you intend to submit the backport as a pull request)
|
||||
git cherry-pick the_sha1_sum
|
||||
git push ...
|
||||
|
||||
If changes are needed, do them and ``git commit -a --amend``
|
||||
|
||||
Things you should NOT do
|
||||
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
(For anyone with push rights to github.com/OSGeo/gdal) Never modify a
|
||||
commit or the history of anything that has been committed to
|
||||
https://github.com/OSGeo/gdal
|
||||
|
|
@ -4,7 +4,9 @@
|
|||
How to contribute?
|
||||
================================================================================
|
||||
|
||||
.. toctree::
|
||||
There are several ways for users to contribute to GDAL:
|
||||
|
||||
developer
|
||||
rst_style
|
||||
* :ref:`contributing code<development>` (bug fixes or enhancements)
|
||||
* filing high-quality `bug reports <https://github.com/osgeo/gdal/issues>`_
|
||||
* improving :ref:`documentation<dev_documentation>`
|
||||
* :ref:`financial sponsorship<sponsors>`
|
||||
|
|
|
|||
|
|
@ -1,62 +1,74 @@
|
|||
.. _build_hints:
|
||||
.. include:: ../substitutions.rst
|
||||
|
||||
.. _building_from_source:
|
||||
|
||||
================================================================================
|
||||
Build hints (cmake)
|
||||
Building GDAL from source
|
||||
================================================================================
|
||||
|
||||
Build requirements
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
The minimum requirements are:
|
||||
|
||||
- CMake >= 3.10, and an associated build system (make, ninja, Visual Studio, etc.)
|
||||
- C99 compiler
|
||||
- C++11 compiler
|
||||
- PROJ >= 6.0
|
||||
|
||||
But a number of optional libraries are also strongly recommended for most builds:
|
||||
SQLite3, expat, libcurl, zlib, libtiff, libgeotiff, libpng, libjpeg, etc.
|
||||
|
||||
CMake
|
||||
CMake (GDAL versions >= 3.5.0)
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
Since version 3.5.0, GDAL can be built using the CMake build system.
|
||||
With the CMake build system you can compile and install GDAL on more or less any
|
||||
platform. After unpacking the source distribution archive step into the source-
|
||||
tree::
|
||||
platform. After unpacking the source distribution archive (or cloning the repository)
|
||||
step into the source tree:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd gdal-{VERSION}
|
||||
|
||||
Create a build directory and step into it::
|
||||
Create a build directory and step into it:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir build
|
||||
cd build
|
||||
|
||||
From the build directory you can now configure CMake, build and install the binaries::
|
||||
From the build directory you can now configure CMake, build and install the binaries:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake ..
|
||||
cmake --build .
|
||||
cmake --build . --target install
|
||||
|
||||
On Windows, one may need to specify generator::
|
||||
.. note::
|
||||
|
||||
For a minimal build, add these options to the initial ``cmake`` command: ``-DGDAL_BUILD_OPTIONAL_DRIVERS=OFF -DOGR_BUILD_OPTIONAL_DRIVERS=OFF``.
|
||||
To enable specific drivers, add ``-DGDAL_ENABLE_DRIVER_<driver_name>=ON`` or ``-DOGR_ENABLE_DRIVER_<driver_name>=ON``.
|
||||
See :ref:`selection-of-drivers` for more details.
|
||||
|
||||
On Windows, one may need to specify generator:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake -G "Visual Studio 15 2017" ..
|
||||
|
||||
If a dependency is installed in a custom location, specify the
|
||||
paths to the include directory and the library::
|
||||
paths to the include directory and the library:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake -DSQLITE3_INCLUDE_DIR=/opt/SQLite/include -DSQLITE3_LIBRARY=/opt/SQLite/lib/libsqlite3.so ..
|
||||
|
||||
Alternatively, a custom prefix can be specified::
|
||||
Alternatively, a custom prefix can be specified:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake -DCMAKE_PREFIX_PATH=/opt/SQLite ..
|
||||
|
||||
You can unset existing cached variables, by using the -U switch of cmake, for example with wildcards::
|
||||
You can unset existing cached variables, by using the -U switch of cmake, for example with wildcards:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake .. -UGDAL_USE_*
|
||||
|
||||
You can assemble dependency settings in a file ``ConfigUser.cmake`` and use it with the -C option.
|
||||
The file contains set() commands that use the CACHE option. You can set for example a different name
|
||||
for the shared lib, *e.g.* ``set (GDAL_LIB_OUTPUT_NAME gdal_x64 CACHE STRING "" FORCE)``::
|
||||
for the shared lib, *e.g.* ``set (GDAL_LIB_OUTPUT_NAME gdal_x64 CACHE STRING "" FORCE)``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake .. -C ConfigUser.cmake
|
||||
|
||||
|
|
@ -1833,6 +1845,8 @@ with it). It is used by the internal libtiff library or the :ref:`raster.zarr` d
|
|||
Control whether to use ZSTD. Defaults to ON when ZSTD is found.
|
||||
|
||||
|
||||
.. _selection-of-drivers:
|
||||
|
||||
Selection of drivers
|
||||
++++++++++++++++++++
|
||||
|
||||
|
|
@ -2153,81 +2167,15 @@ Driver specific options
|
|||
into the build tree and build the needed files from it into the driver.
|
||||
|
||||
|
||||
Building on Windows with Conda dependencies and Visual Studio
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
It is less appropriate for Debug builds of GDAL, than other methods, such as using vcpkg.
|
||||
|
||||
Install git
|
||||
+++++++++++
|
||||
|
||||
Install `git <https://git-scm.com/download/win>`_
|
||||
|
||||
Install miniconda
|
||||
+++++++++++++++++
|
||||
|
||||
Install `miniconda <https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe>`_
|
||||
|
||||
Install GDAL dependencies
|
||||
+++++++++++++++++++++++++
|
||||
|
||||
Start a Conda enabled console and assuming there is a c:\\dev directory
|
||||
|
||||
::
|
||||
|
||||
cd c:\dev
|
||||
conda create --name gdal
|
||||
conda activate gdal
|
||||
conda install --yes --quiet curl libiconv icu git python=3.7 swig numpy pytest zlib clcache
|
||||
conda install --yes --quiet -c conda-forge compilers
|
||||
conda install --yes --quiet -c conda-forge \
|
||||
cmake proj geos hdf4 hdf5 \
|
||||
libnetcdf openjpeg poppler libtiff libpng xerces-c expat libxml2 kealib json-c \
|
||||
cfitsio freexl geotiff jpeg libpq libspatialite libwebp-base pcre postgresql \
|
||||
sqlite tiledb zstd charls cryptopp cgal librttopo libkml openssl xz
|
||||
|
||||
.. note::
|
||||
|
||||
The ``compilers`` package will install ``vs2017_win-64`` (at time of writing)
|
||||
to set the appropriate environment for cmake to pick up. It is also possible
|
||||
to use the ``vs2019_win-64`` package if Visual Studio 2019 is to be used.
|
||||
|
||||
Checkout GDAL sources
|
||||
+++++++++++++++++++++
|
||||
|
||||
::
|
||||
|
||||
cd c:\dev
|
||||
git clone https://github.com/OSGeo/gdal.git
|
||||
|
||||
Build GDAL
|
||||
++++++++++
|
||||
|
||||
From a Conda enabled console
|
||||
|
||||
::
|
||||
|
||||
conda activate gdal
|
||||
cd c:\dev\gdal
|
||||
cmake -S . -B build -DCMAKE_PREFIX_PATH:FILEPATH="%CONDA_PREFIX%" \
|
||||
-DCMAKE_C_COMPILER_LAUNCHER=clcache
|
||||
-DCMAKE_CXX_COMPILER_LAUNCHER=clcache
|
||||
cmake --build build --config Release -j 8
|
||||
|
||||
.. only:: FIXME
|
||||
|
||||
Run GDAL tests
|
||||
++++++++++++++
|
||||
|
||||
::
|
||||
|
||||
cd c:\dev\GDAL
|
||||
cd _build.vs2019
|
||||
ctest -V --build-config Release
|
||||
|
||||
Cross-compiling for Android
|
||||
+++++++++++++++++++++++++++
|
||||
|
||||
First refer to https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-android
|
||||
and to https://github.com/OSGeo/gdal/blob/master/.github/workflows/android_cmake/start.sh for
|
||||
an example of a build script to cross-compile from Ubuntu.
|
||||
|
||||
Autoconf/nmake (GDAL versions < 3.5.0)
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
See https://trac.osgeo.org/gdal/wiki/BuildHints for hints for GDAL < 3.5
|
||||
autoconf and nmake build systems.
|
||||
|
|
@ -1,13 +1,37 @@
|
|||
.. include:: ../substitutions.rst
|
||||
|
||||
.. _dev_documentation:
|
||||
|
||||
================================================================================
|
||||
Building documentation
|
||||
================================================================================
|
||||
|
||||
Documentation overview
|
||||
###########################
|
||||
|
||||
GDAL's documentation includes C and C++ :ref:`API documentation <api>` built
|
||||
automatically from source comments using doxygen and reStructuredText (rst)
|
||||
files containing manually-edited content.
|
||||
|
||||
|Sphinx| is used to combine the above components into a complete set of documentation in HTML, PDF, and other formats.
|
||||
|
||||
Building documentation
|
||||
######################
|
||||
|
||||
HTML documentation can be built by running ``make html`` in the ``doc`` subdirectory of the GDAL source repository.
|
||||
The generated files will be output to ``doc/build`` where they can be viewed using a web browser.
|
||||
|
||||
To visualize documentation changes while editing, it may be useful to install the |sphinx-autobuild| python package.
|
||||
Once installed, running ``sphinx-autobuild -b html source build`` from the ``doc`` subdirectory will build documentation
|
||||
and serve it on a local web server at ``http://127.0.0.1:8000``. The pages served will be automatically refreshed as changes
|
||||
are made to underlying ``rst`` documentatio files.
|
||||
|
||||
.. _rst_style:
|
||||
|
||||
================================================================================
|
||||
Sphinx RST Style guide
|
||||
================================================================================
|
||||
######################
|
||||
|
||||
This page contains syntax rules, tips, and tricks for using Sphinx and reStructuredText. For more information, please see this `comprehensive guide to reStructuredText <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_, as well as the `Sphinx reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`_.
|
||||
|
||||
Basic markup
|
||||
------------
|
||||
This section contains syntax rules, tips, and tricks for using Sphinx and reStructuredText. For more information, please see this `comprehensive guide to reStructuredText <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_, as well as the `Sphinx reStructuredText Primer <http://sphinx.pocoo.org/rest.html>`_.
|
||||
|
||||
Basic markup
|
||||
------------
|
||||
|
|
@ -31,7 +55,7 @@ A reStructuredText document is written in plain text. Without the need for comp
|
|||
- `` ``monospace`` `` (double back quote)
|
||||
- ``monospace``
|
||||
|
||||
.. warning:: Use of basic markup is **not recommend**! Where possible use sphinx inline directives to logically mark commands, parameters, options, input, and files. By using directives consistently these items can be styled appropriately.
|
||||
.. warning:: Use of basic markup is **not recommend**! Where possible use sphinx inline directives (described below) to logically mark commands, parameters, options, input, and files. By using directives consistently these items can be styled appropriately.
|
||||
|
||||
Lists
|
||||
-----
|
||||
|
|
@ -280,4 +304,4 @@ Use ``describe`` to document create parameters::
|
|||
|
||||
.. describe:: WORLDFILE=YES
|
||||
|
||||
Force the generation of an associated ESRI world file (with the extension .wld).
|
||||
Force the generation of an associated ESRI world file (with the extension .wld).
|
||||
|
|
@ -0,0 +1,152 @@
|
|||
.. include:: ../substitutions.rst
|
||||
|
||||
.. _dev_environment:
|
||||
|
||||
================================================================================
|
||||
Setting up a development environment
|
||||
================================================================================
|
||||
|
||||
.. _build_requirements:
|
||||
|
||||
Build requirements
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
The minimum requirements are:
|
||||
|
||||
- CMake >= 3.10, and an associated build system (make, ninja, Visual Studio, etc.)
|
||||
- C99 compiler
|
||||
- C++11 compiler
|
||||
- PROJ >= 6.0
|
||||
- SWIG >= 4.0.2, for building bindings to other programming languages, such as Python
|
||||
- Python, for running the test suite
|
||||
|
||||
A number of optional libraries are also strongly recommended for most builds:
|
||||
SQLite3, expat, libcurl, zlib, libtiff, libgeotiff, libpng, libjpeg, etc.
|
||||
Consult :ref:`raster_drivers` and :ref:`vector_drivers` pages for information
|
||||
on dependencies of optional drivers.
|
||||
|
||||
.. note::
|
||||
|
||||
If SWIG 4.0.2 is not provided by system package manager, it can be built and installed from source using the following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export SWIG_PREFIX=/path/to/install
|
||||
export SWIG_VERSION=4.0.2
|
||||
|
||||
mkdir /tmp/swig/
|
||||
cd /tmp/swig/
|
||||
wget https://sourceforge.net/projects/swig/files/swig/swig-${SWIG_VERSION}/swig-${SWIG_VERSION}.tar.gz/download -O swig-${SWIG_VERSION}.tar.gz
|
||||
tar xf swig-${SWIG_VERSION}.tar.gz
|
||||
cd swig-${SWIG_VERSION}
|
||||
./configure --prefix=$SWIG_PREFIX
|
||||
make
|
||||
make install
|
||||
export PATH=$SWIG_PREFIX/bin:$PATH
|
||||
|
||||
The path to the updated version of SWIG can be provided to provided to ``cmake`` using ``-DSWIG_EXECUTABLE=$SWIG_PREFIX/bin/swig``.
|
||||
|
||||
|
||||
Vagrant
|
||||
-------
|
||||
|
||||
`Vagrant <https://www.vagrantup.com>`_ is a tool that works with a virtualization product such as
|
||||
VirtualBox to create a reproducible development environment. GDAL includes a Vagrant configuration
|
||||
file that sets up an Ubuntu virtual machine with a comprehensive set of dependencies.
|
||||
|
||||
Once Vagrant has been installed and the GDAL source downloaded, the virtual machine can be set up
|
||||
by running the following from the source root directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# VAGRANT_VM_CPU=number_of_cpus
|
||||
vagrant up
|
||||
|
||||
The source root directory is exposed inside the virtual machine at ``/vagrant``, so changes made to
|
||||
GDAL source files on the host are seen inside the VM. To rebuild GDAL after changing source files,
|
||||
you can connect to the VM and re-run the build command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
vagrant ssh
|
||||
cmake --build .
|
||||
|
||||
Note that the following directories on the host will be created (and can be
|
||||
removed if the Vagrant environment is no longer needed):
|
||||
|
||||
- ``../apt-cache/ubuntu/jammy64``: contains a cache of Ubuntu packages of the VM,
|
||||
to allow faster VM reconstruction
|
||||
- ``build_vagrant``: CMake build directory
|
||||
- ``ccache_vagrant``: CCache directory
|
||||
|
||||
Building on Windows with Conda dependencies and Visual Studio
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
It is less appropriate for Debug builds of GDAL, than other methods, such as using vcpkg.
|
||||
|
||||
Install git
|
||||
+++++++++++
|
||||
|
||||
Install `git <https://git-scm.com/download/win>`_
|
||||
|
||||
Install miniconda
|
||||
+++++++++++++++++
|
||||
|
||||
Install `miniconda <https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe>`_
|
||||
|
||||
Install GDAL dependencies
|
||||
+++++++++++++++++++++++++
|
||||
|
||||
Start a Conda enabled console and assuming there is a c:\\dev directory
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd c:\dev
|
||||
conda create --name gdal
|
||||
conda activate gdal
|
||||
conda install --yes --quiet curl libiconv icu git python=3.7 swig numpy pytest zlib clcache
|
||||
conda install --yes --quiet -c conda-forge compilers
|
||||
conda install --yes --quiet -c conda-forge \
|
||||
cmake proj geos hdf4 hdf5 \
|
||||
libnetcdf openjpeg poppler libtiff libpng xerces-c expat libxml2 kealib json-c \
|
||||
cfitsio freexl geotiff jpeg libpq libspatialite libwebp-base pcre postgresql \
|
||||
sqlite tiledb zstd charls cryptopp cgal librttopo libkml openssl xz
|
||||
|
||||
.. note::
|
||||
|
||||
The ``compilers`` package will install ``vs2017_win-64`` (at time of writing)
|
||||
to set the appropriate environment for cmake to pick up. It is also possible
|
||||
to use the ``vs2019_win-64`` package if Visual Studio 2019 is to be used.
|
||||
|
||||
Checkout GDAL sources
|
||||
+++++++++++++++++++++
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd c:\dev
|
||||
git clone https://github.com/OSGeo/gdal.git
|
||||
|
||||
Build GDAL
|
||||
++++++++++
|
||||
|
||||
From a Conda enabled console
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
conda activate gdal
|
||||
cd c:\dev\gdal
|
||||
cmake -S . -B build -DCMAKE_PREFIX_PATH:FILEPATH="%CONDA_PREFIX%" \
|
||||
-DCMAKE_C_COMPILER_LAUNCHER=clcache
|
||||
-DCMAKE_CXX_COMPILER_LAUNCHER=clcache
|
||||
cmake --build build --config Release -j 8
|
||||
|
||||
.. only:: FIXME
|
||||
|
||||
Run GDAL tests
|
||||
++++++++++++++
|
||||
|
||||
::
|
||||
|
||||
cd c:\dev\GDAL
|
||||
cd _build.vs2019
|
||||
ctest -V --build-config Release
|
||||
|
|
@ -0,0 +1,144 @@
|
|||
.. _development_practices:
|
||||
|
||||
.. include:: ../substitutions.rst
|
||||
|
||||
================================================================================
|
||||
Development practices
|
||||
================================================================================
|
||||
|
||||
Making changes to GDAL
|
||||
----------------------
|
||||
|
||||
Minor changes to GDAL, such as bug fixes, may be made by opening a GitHub pull request.
|
||||
|
||||
Major changes should be discussed on the |gdal-dev| listserv and may require the drafting
|
||||
of a RFC (request for comment) document.
|
||||
|
||||
GDAL's policy on substantial code additions is documented at :ref:`rfc-85`.
|
||||
|
||||
|
||||
Git usage
|
||||
---------
|
||||
|
||||
This section collects a few best practices for git usage for GDAL development.
|
||||
|
||||
Initiating your work repository
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Fork |OSGeo/gdal| from the GitHub UI, and then run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/DSGeo/gdal
|
||||
cd gdal
|
||||
git remote add my_user_name git@github.com:my_user_name/gdal.git
|
||||
|
||||
Working with a feature branch
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git checkout master
|
||||
# potentially update your local master against upstream, as described above
|
||||
git checkout -b my_new_feature_branch
|
||||
|
||||
# do work. For example:
|
||||
git add my_new_file
|
||||
git add my_modifid_message
|
||||
git rm old_file
|
||||
git commit -a
|
||||
|
||||
# you may need to resynchronize against master if you need some bugfix
|
||||
# or new capability that has been added since you created your branch
|
||||
git fetch origin
|
||||
git rebase origin/master
|
||||
|
||||
# At end of your work, make sure history is reasonable by folding non
|
||||
# significant commits into a consistent set
|
||||
git rebase -i master
|
||||
# use 'fixup' for example to merge several commits together,
|
||||
# and 'reword' to modify commit messages
|
||||
|
||||
# or alternatively, in case there is a big number of commits and marking
|
||||
# all them as 'fixup' is tedious
|
||||
git fetch origin
|
||||
git rebase origin/master
|
||||
git reset --soft origin/master
|
||||
git commit -a -m "Put here the synthetic commit message"
|
||||
|
||||
# push your branch
|
||||
git push my_user_name my_new_feature_branch
|
||||
|
||||
|
||||
From the GitHub UI, issue a pull request.
|
||||
|
||||
If the pull request discussion or automated checks require changes, commit
|
||||
locally and push. To get a reasonable history, you may need to combine commits
|
||||
using ``git rebase -i master``, in which case you will have to force-push your
|
||||
branch with ``git push -f my_user_name my_new_feature_branch``.
|
||||
|
||||
|
||||
Updating your local master against upstream master
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git checkout master
|
||||
git fetch origin
|
||||
|
||||
# Be careful: this will lose all local changes you might have done now
|
||||
git reset --hard origin/master
|
||||
|
||||
Commit messages
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Commit messages should indicate a component name (eg a driver name), a short
|
||||
description, and when relevant, a reference to a issue (with 'fixes #' if it
|
||||
actually fixes it)
|
||||
|
||||
::
|
||||
|
||||
COMPONENT_NAME: fix bla bla (fixes #1234)
|
||||
|
||||
Details here...
|
||||
|
||||
Commit hooks
|
||||
^^^^^^^^^^^^
|
||||
|
||||
GDAL provides pre-commit hooks to run code linters before a commit is made. The
|
||||
hooks are cloned with the repository and can be installed using
|
||||
`pre-commit <https://pre-commit.com>`_:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python -m pip install pre-commit
|
||||
pre-commit install
|
||||
|
||||
|
||||
Once installed, the hooks can be run manually via ``pre-commit run --all-files``.
|
||||
|
||||
Backporting bugfixes from master to a stable branch
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git checkout master
|
||||
With git log, identify the sha1sum of the commit you want to backport
|
||||
git checkout 2.2 # if you want to backport to 2.2
|
||||
git pull origin 2.2
|
||||
# git checkout -b branch_name # if you intend to submit the backport as a pull request
|
||||
git cherry-pick the_sha1_sum
|
||||
git push ...
|
||||
|
||||
If changes are needed, do them and ``git commit -a --amend``
|
||||
|
||||
|
||||
Things you should NOT do
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
(For anyone with push rights to |OSGeo/gdal|) Never modify a commit or
|
||||
the history of anything that has been
|
||||
committed to https://github.com/OSGeo/gdal
|
||||
|
||||
Committing symbolic links is allowed only under the .github directory in order to
|
||||
avoid potential problems on Windows.
|
||||
|
|
@ -1,3 +1,6 @@
|
|||
.. _development:
|
||||
|
||||
|
||||
================================================================================
|
||||
Development
|
||||
================================================================================
|
||||
|
|
@ -5,5 +8,10 @@ Development
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
dev_environment
|
||||
building_from_source
|
||||
testing
|
||||
dev_practices
|
||||
dev_documentation
|
||||
cmake
|
||||
rfc/index
|
||||
|
|
|
|||
|
|
@ -0,0 +1,69 @@
|
|||
.. _testing:
|
||||
|
||||
.. include:: ../substitutions.rst
|
||||
|
||||
================================================================================
|
||||
Automated testing
|
||||
================================================================================
|
||||
|
||||
GDAL includes a comprehensive test suite, implemented using a combination of Python (via pytest) and C++ (via TUT).
|
||||
|
||||
After building GDAL using CMake, the complete test suite can be run using ``ctest -v --output-on-failure``. This will automatically set environment variables so that tests are run on the
|
||||
the built version of GDAL, rather than an installed system copy.
|
||||
|
||||
Running a subset of tests using ``ctest``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The complete set of test suites known to ``ctest`` can be viewed running ``ctest -N``.
|
||||
|
||||
A subset of tests can be run using the ``-R`` argument to ``ctest``, which selects tests using a provided regular expression.
|
||||
For example, ``ctest -R autotest`` would run the Python-based tests.
|
||||
|
||||
The ``-E`` argument can be used to exclude tests using a regular expression. For example, ``ctest -E performance`` would exclude (slow) performance benchmarks.
|
||||
|
||||
Running a subset of tests using ``pytest``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The test subsets exposed by ``ctest`` are still rather large and some may take several minutes to run.
|
||||
If a higher level of specificity is needed, ``pytest`` can be called directly to run groups of tests or individual tests.
|
||||
Before running ``pytest``, it is important to set environment variables so that the development build of GDAL is tested,
|
||||
rather than a system version. This can be done by sourcing the following from the build directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. ../scripts/setdevenv.sh
|
||||
|
||||
(with adjustments to the above path if the build directory is not a subdirectory of the GDAL source root).
|
||||
To verify that environment variables were set correctly, you can check the version of a GDAL binary:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
gdalinfo --version
|
||||
# GDAL 3.7.0dev-5327c149f5-dirty, released 2018/99/99 (debug build)
|
||||
|
||||
and the Python bindings:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python3 -c 'from osgeo import gdal; print(gdal.__version__)'
|
||||
# 3.7.0dev-5327c149f5-dirty
|
||||
|
||||
List tests containing "tiff" in the name:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pytest --collect-only autotest -k tiff
|
||||
|
||||
Running an individual test file
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pytest autotest/gcore/vrt_read.py
|
||||
|
||||
Running an individual test
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pytest autotest/gcore/vrt_read.py -k test_vrt_read_non_existing_source
|
||||
|
||||
.. warning:: Not all Python tests can be run independently; some tests depend on state set by a previous tests in the same file.
|
||||
|
|
@ -198,7 +198,7 @@ Past Releases
|
|||
Development Source
|
||||
------------------------------------------------------------------------------
|
||||
|
||||
The main repository for GDAL is located on github at
|
||||
The main repository for GDAL is located on GitHub at
|
||||
https://github.com/OSGeo/GDAL.
|
||||
|
||||
You can obtain a copy of the active source code by issuing the following
|
||||
|
|
@ -209,25 +209,7 @@ command
|
|||
git clone https://github.com/OSGeo/GDAL.git
|
||||
|
||||
|
||||
Build requirements
|
||||
..................
|
||||
|
||||
To build GDAL 3 or later, you need *at a minimum* a C++11 compatible compiler, and
|
||||
`PROJ 6 or later <https://proj.org>`_.
|
||||
This will only give you a minimum build which will lack a lot of drivers.
|
||||
Consult :ref:`raster_drivers` and :ref:`vector_drivers` pages for additional optional
|
||||
dependencies.
|
||||
|
||||
|
||||
Build instructions
|
||||
..................
|
||||
|
||||
From GDAL 3.5, :ref:`CMake-based build <build_hints>` is available, and required
|
||||
since GDAL 3.6
|
||||
|
||||
See https://trac.osgeo.org/gdal/wiki/BuildHints for hints for GDAL < 3.5
|
||||
autoconf and nmake build systems.
|
||||
|
||||
Additional information is available about :ref:`build_requirements` and :ref:`building_from_source`.
|
||||
|
||||
Binaries
|
||||
------------------------------------------------------------------------------
|
||||
|
|
@ -330,8 +312,3 @@ Images with nightly builds of GDAL master and tagged releases are available at
|
|||
|
||||
Information on the content of the different configurations can be found at
|
||||
`https://github.com/OSGeo/gdal/tree/master/docker <https://github.com/OSGeo/gdal/tree/master/docker>`_
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 0
|
||||
|
||||
build_hints
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ Build Instructions
|
|||
CMake builds
|
||||
++++++++++++
|
||||
|
||||
See the ``GDAL_USE_PUBLICDECOMPWT`` option of :ref:`build_hints`.
|
||||
See the ``GDAL_USE_PUBLICDECOMPWT`` option of :ref:`building_from_source`.
|
||||
|
||||
Other build systems
|
||||
+++++++++++++++++++
|
||||
|
|
|
|||
|
|
@ -11,3 +11,7 @@
|
|||
.. |Bash| replace:: `Bash <https://en.wikipedia.org/wiki/Bash_(Unix_shell)>`__
|
||||
.. |Python| replace:: `Python <https://python.org/>`__
|
||||
.. |Docker| replace:: `Docker <https://www.docker.com/>`__
|
||||
.. |gdal-dev| replace:: `gdal-dev <https://lists.osgeo.org/mailman/listinfo/gdal-dev>`__
|
||||
.. |OSGeo/gdal| replace:: `OSGeo/gdal <https://github.com/OSGeo/gdal>`__
|
||||
.. |Sphinx| replace:: `Sphinx <https://www.sphinx-doc.org/>`__
|
||||
.. |sphinx-autobuild| replace:: `sphinx-autobuild <https://pypi.org/project/sphinx-autobuild/>`__
|
||||
|
|
|
|||
Loading…
Reference in New Issue