Checkout source code
Apache SIS source code is maintained using Git version control, completed by optional data maintained using Subversion version control. Optional data include in particular the EPSG geodetic dataset, which is subject to licensing terms different than Apache ones. This page describes two ways to checkout Apache SIS source code:
- A basic checkout with only the main repository, the most stable branch, and no configuration requirement.
- A more advanced configuration for active SIS developments, using uncommitted (for now) API and including optional data for more extensive tests.
It is possible to start with the basic checkout and migrate to the advanced configuration later, or to cherry-pick only the interesting parts of the advanced configuration.
Create an empty directory for the Apache SIS project.
ApacheSIS directory name in this page, but that name can be anything;
replace that name in the shell commands below if another name is used.
The Apache SIS source code can be cloned in that directory as below
(lines starting with
# are comments and can be ignored):
mkdir ApacheSIS cd ApacheSIS git clone https://gitbox.apache.org/repos/asf/sis # # Alternatively, GitHub mirror can also be used: # git clone https://github.com/apache/sis # # or Subversion (read-only): # svn checkout https://github.com/apache/sis/trunk
That is all. Apache SIS can be built by running
mvn install in the
At this stage, the
ApacheSIS parent directory is redundant with the
but we recommend to create that parent directory anyway in anticipation
for more subdirectories to be created later, when desired.
The remaining of this page describes those optional configurations for more advanced developments.
This section assumes that above-described basic checkout has been done. All subsections below are optional. It is not mandatory to execute all of them, but we recommend to at least create the data directory described below because some other optional services depend on it.
Create data directory
Apache SIS needs a directory where to store database, datum shift files and other optional data.
That directory is specified by the
SIS_DATA environment variable and can be located anywhere.
A convenient location is a subdirectory of the
ApacheSIS directory created in the “basic checkout” section.
For example (with
ApacheSIS as the current directory):
mkdir Data export SIS_DATA=$PWD/Data # # For making that environment variable available in future shell sessions, # the output of following command can be added to .bash_profile or .bashrc # file in user home directory. # echo export SIS_DATA=$SIS_DATA
Checkout non-free data
The EPSG geodetic dataset is recommended for operations related to Coordinate Reference Systems.
Without the EPSG database, only a small subset
of coordinate reference systems can be created from EPSG codes.
The EPSG database can be installed in various ways,
but this section describes an alternative way more suitable to Apache SIS development.
Then following command can be executed with
ApacheSIS as the current directory:
Then copy or link the EPSG scripts in the directory where Apache SIS looks for optional data.
Adjust the relative paths as needed if the
SIS_DATA environment variable
points to another location than the one used in above section:
mkdir $SIS_DATA/Databases mkdir $SIS_DATA/Databases/ExternalSources cd $SIS_DATA/Databases/ExternalSources ln -s ../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/Data.sql EPSG_Data.sql ln -s ../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/FKeys.sql EPSG_FKeys.sql ln -s ../../../non-free/sis-epsg/src/main/resources/org/apache/sis/referencing/factory/sql/epsg/Tables.sql EPSG_Tables.sql cd -
This is sufficient for allowing Apache SIS to create the geodetic database
without the need for
sis-embedded-data module on the classpath.
This setting is not done automatically because Apache projects cannot introduce
non-free dependencies without explicit action from user.
If this action is not taken, some JUnit tests requiring EPSG data may be skipped.
If any EPSG file is updated, deleting the
is sufficient for causing Apache SIS to recreate the Derby database with new data.
Apache SIS is tested with Derby, HSQL and PostgreSQL databases. Derby and HSQL are tested automatically using temporary databases in memory. But testing on PostgreSQL requires the creation of a dedicated database on the developer platform. The requirements are:
- PostgreSQL server running and listening to
localhoston default port (5432).
- A role with the same name than Unix user name of the developer running tests.
- An empty database named
- Above-cited role can connect to
SpatialMetadataTestdatabase without password.
org.apache.sis.test.extensiveJava property set to
SpatialMetadataTest database should stay empty when not running tests,
because Apache SIS always delete the temporary schema after tests completion,
regardless if the tests were successful or not.
The role and database can be created by the following SQL instructions
my_unix_user_name by your actual user name):
CREATE ROLE my_unix_user_name LOGIN; CREATE DATABASE "SpatialMetadataTest" WITH OWNER = my_unix_user_name; COMMENT ON DATABASE "SpatialMetadataTest" IS 'For Apache SIS tests only.';
For opening access to that database without password, it may be necessary
to add following line (ignoring comment lines) in the
Location of this file is system-dependent; it may be
# IPv4 local connections: # TYPE DATABASE USER ADDRESS METHOD host SpatialMetadataTest my_unix_user_name 127.0.0.1/32 trust
The last step for allowing Apache SIS to run tests on PostgreSQL is to set the
org.apache.sis.test.extensive Java property to
true (see next section).
This requirement has been added for avoiding undesired interference with host.
Note that this step is likely to change after Apache SIS upgrade to JUnit 5.
Running extensive tests
mvn install execution in the
will build and test Apache SIS with the default set of JUnit tests.
Some tests are skipped by default, either because they would have some effects outside
sis directory (for example writing in
SpatialMetadataTest database on PostgreSQL),
or because those tests take a long time to execute.
For enabling all tests, use the following command:
cd sis mvn install -Dorg.apache.sis.test.extensive=true
Switch to development branch
The source code repository contains
Apache SIS releases are created from
master, which depends on the latest GeoAPI version
released by the Open Geospatial Consortium (OGC), currently GeoAPI 3.0.1.
However daily developments occur on the
geoapi-4.0 branch before to be merged (indirectly) to
Those branches exist in order to experiment early new API and technologies — since they may impact
the library design — while keeping the releases compatible with officially released API.
geoapi-4.0branch implements interfaces defined in GeoAPI 4.0 snapshots.
geoapi-3.1branch implements interfaces defined in GeoAPI 3.1 snapshots.
masterimplements interfaces defined by the GeoAPI 3.0.1 stable release.
geoapi-4.0 branch are merged to
geoapi-3.1 branch, which is then merged to
When commits reach
master they become unmodifiable; the
git push --force command is not allowed on that branch.
Contributors to Apache SIS project should switch to the current development branch before submitting patches:
cd sis git checkout geoapi-4.0
Note that those
geoapi-xxx branches may disappear or be replaced by something else
after OGC releases the corresponding GeoAPI versions.
All developments and tags prior Apache SIS 1.0 were done on a Subversion repository
and can be browsed online.
Tags for Apache SIS versions 0.1 to 0.8 should be fetched from the SVN repository.
The development branches on that repository were named