This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sis-site.git
commit be694f71edfb3ebb90496e21f797d8721b0c17f5
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Mon Oct 2 18:19:09 2023 +0200
Merge the "build" page with the "sources" and "downloads" pages.
---
content/build.md | 59 ----------------------------------------------
content/downloads.md | 36 +++++++++++++++++++++++++---
content/source.md | 37 ++++++++++++++++++++++++++++-
layouts/partials/menu.html | 1 -
4 files changed, 69 insertions(+), 64 deletions(-)
diff --git a/content/build.md b/content/build.md
deleted file mode 100644
index e59c67d1..00000000
--- a/content/build.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: Build from source
----
-
-Apache {{% SIS %}} is built by Gradle.
-It requires Java 18 or higher for building, but the compilation result can be
executed on Java 11 or higher.
-For installing the JAR files in the local Maven repository, execute the
following command
-from the SIS project root:
-
-{{< highlight bash >}}
-gradle assemble publishToMavenLocal
-{{< / highlight >}}
-
-The JavaFX application is excluded by default because it depends on
-the [JavaFX platform][JavaFX] which is distributed under GPL license
-(note that the SIS module stay under Apache 2 licence).
-Likewise the [EPSG geodetic dataset](epsg.html) is excluded by default for
licensing reasons.
-For including the JavaFX module in the build, define the `PATH_TO_FX`
environment variable
-with the path to the directory containing all JavaFX JAR files.
-Example on a Linux system (the path may vary):
-
-{{< highlight bash >}}
-export PATH_TO_FX=/usr/lib/jvm/openjfx
-{{< / highlight >}}
-
-The remaining of this page provides more advanced tips for SIS developers.
-
-{{< toc >}}
-
-# Distribution file {#dist}
-
-The distribution archive is a file with the `.zip` extension containing most
SIS modules
-(excluding the ones in the incubator sub-project), together with mandatory
dependencies.
-For users convenience, we provide shell scripts launching the SIS command line
tool or the JavaFX application.
-Those shell scripts, together with other files (`README`, `LICENSE`,
<i>etc.</i>) are bundled in a ZIP file
-created in the `optional/build/bundle/` directory.
-To test, uncompress in any directory and execute
`apache-sis-<version>/bin/sis`.
-
-# SIS-specific Gradle plugin {#build-helper}
-
-Apache {{% SIS %}} uses a plugin in `buildSrc/` for SIS-specific tasks and
Javadoc customization.
-This plugin is used automatically by Gradle. Consequently the remaining of
this page can be safely ignored.
-This page is provided only as a reference for developers wanting to take a
closer look to SIS build system.
-
-## Localized resources compiler {#resources}
-
-Localized resources are provided in `*.properties` files as specified by the
`java.util.PropertyResourceBundle` standard class.
-However SIS does not use those resources files directly. Instead
`*.properties` files are transformed into binary files having
-the same filename but the `.utf` extension. This conversion is done for
efficiency, for convenience (the compiler applies the
-`java.text.MessageFormat` _doubled single quotes_ rule itself), and for
compile-time safety.
-
-In addition to generating the `*.utf` files, the resource compiler may modify
the `*.java` files having the same name than the
-resource files. For example given a set of `Vocabulary*.properties` files (one
for each supported language), the compiler will
-generate the corresponding `Vocabulary*.utf` files, then look for a
`Vocabulary.java` source file. If such source file is found
-and contains a public static inner class named `Keys`, then the compiler will
rewrite the constants declared in that inner class
-with the list of keys found in the `Vocabulary*.properties` files.
-
-
-[JavaFX]: https://openjfx.io/
diff --git a/content/downloads.md b/content/downloads.md
index b089844c..1b3aee8e 100644
--- a/content/downloads.md
+++ b/content/downloads.md
@@ -4,7 +4,6 @@ title: Apache SIS downloads
Apache {{% SIS %}} {{% version %}} is now available.
See the [release notes](release-notes/{{% version %}}.html) for a list of
changes since the previous version.
-See the [build instruction](build.html) for compiling from the sources.
Apache {{% SIS %}} releases are available under the [Apache License, Version
2.0][license].
See the `NOTICE` file contained in each release artifact for applicable
copyright attribution notices.
@@ -21,7 +20,7 @@ Optional dependencies (JAXB implementation, UCAR netCDF
library, Amazon SDK) are
* [Apache SIS {{% version %}} binary][bin] \[[PGP][bin-PGP]\] \[[SHA
512][bin-SHA]\]
* [Apache SIS {{% version %}} javadoc][doc] \[[PGP][doc-PGP]\] \[[SHA
512][doc-SHA]\]
-* [Apache SIS {{% version %}} sources][src] \[[PGP][src-PGP]\] \[[SHA
512][src-SHA]\] ([build instruction](build.html))
+* [Apache SIS {{% version %}} sources][src] \[[PGP][src-PGP]\] \[[SHA
512][src-SHA]\]
## Verify signatures {#release-gpg}
@@ -54,7 +53,37 @@ pgpv apache-sis-{{% version %}}-src.zip.asc
{{< / highlight >}}
-## Setting the module-path
+## Build from the sources {#build}
+
+If the source files were donwloaded instead of the binaries, the sources will
need to be built by Gradle.
+It requires Java 18 or higher for building, but the compilation result can be
executed on Java 11 or higher.
+For installing the JAR files in the local Maven repository, execute the
following command
+from the SIS project root:
+
+{{< highlight bash >}}
+cd apache-sis-{{% version %}}
+gradle test # Theoretically optional, seems sometime
necessary.
+gradle assemble
+gradle publishToMavenLocal # If use with Maven projects is desired.
+{{< / highlight >}}
+
+The JavaFX application is excluded by default because it depends on
+the [JavaFX platform][JavaFX] which is distributed under GPL license
+(note that the SIS module stay under Apache 2 licence).
+Likewise the [EPSG geodetic dataset](epsg.html) is excluded by default for
licensing reasons.
+For including the JavaFX module in the build, define the `PATH_TO_FX`
environment variable
+with the path to the directory containing all JavaFX JAR files.
+Example on a Linux system (the path may vary):
+
+{{< highlight bash >}}
+export PATH_TO_FX=/usr/lib/jvm/openjfx
+{{< / highlight >}}
+
+The application will bundled in a ZIP file in the `optional/build/bundle`
directory.
+To test, uncompress in any directory and execute `apache-sis-{{% version
%}}/bin/sisfx`.
+
+
+## Setting the module-path {#module-path}
Apache SIS 1.4 and later use the Java Platform Module System (JPMS).
Consequently applications should declare SIS JAR files on their module-path
rather than their class-path.
@@ -161,3 +190,4 @@ See [How to use EPSG geodetic dataset](epsg.html) page for
more information.
[bin-SHA]: https://www.apache.org/dist/sis/{{% version %}}/apache-sis-{{%
version %}}-bin.zip.sha512
[EPSG]: https://epsg.org/
[EPSG-ToU]: https://epsg.org/terms-of-use.html
+[JavaFX]: https://openjfx.io/
diff --git a/content/source.md b/content/source.md
index be082f97..c7b768c0 100644
--- a/content/source.md
+++ b/content/source.md
@@ -41,13 +41,17 @@ git clone https://gitbox.apache.org/repos/asf/sis
If JavaFX is available on the local machine,
its JAR files location can be specified as below
(edit the `/usr/lib/jvm/openjfx` path as needed).
-This is optional and can be safely ignored if the JavaFX application is not
desired.
+The JavaFX application is excluded by default because it depends on
+the [JavaFX platform][JavaFX] which is distributed under GPL license
+(note that the SIS module stay under Apache 2 licence).
{{< highlight bash >}}
# Syntax for Unix shell
export PATH_TO_FX=/usr/lib/jvm/openjfx
{{< / highlight >}}
+Likewise the [EPSG geodetic dataset](epsg.html) is excluded by default for
licensing reasons.
+
Then, Apache {{% SIS %}} can be built as below:
{{< highlight bash >}}
@@ -92,6 +96,7 @@ export SIS_DATA=$PWD/Data
echo export SIS_DATA=$SIS_DATA
{{< / highlight >}}
+
## Checkout non-free data {#non-free}
The EPSG geodetic dataset is recommended for operations related to Coordinate
Reference Systems.
@@ -129,6 +134,7 @@ If this action is not taken, some JUnit tests requiring
EPSG data may be skipped
If any EPSG file is updated, deleting the
`$SIS_DATA/Databases/SpatialMetadata` directory
is sufficient for causing Apache {{% SIS %}} to recreate the Derby database
with new data.
+
## Configure PostgreSQL {#postgres}
Apache {{% SIS %}} is tested with Derby, HSQL and PostgreSQL databases.
@@ -179,6 +185,7 @@ The last step for allowing Apache {{% SIS %}} to run tests
on PostgreSQL is to s
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 {#tests}
A simple `gradle test` execution in the `sis` directory
@@ -193,6 +200,7 @@ cd sis
gradle test --system-prop org.apache.sis.test.extensive=true
{{< / highlight >}}
+
## Switch to development branch {#branches}
The source code repository contains `main`, `geoapi-3.1` and `geoapi-4.0`
branches.
@@ -219,6 +227,33 @@ 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.
+
+# Managing resources {#resources}
+
+Resources are in the same `src` directories than Java source code.
+Resources files are kept close to Java source files because they often need to
be edited together.
+All resource files are copied to the build directory, except those with the
following extensions:
+
+* `tmp`, `bak`, `log` — because they are temporary files.
+* `java`, `idl` — because they are source files.
+* `html`, `md` — because they are documentation files.
+
+The `properties` files are handled in a special way.
+Localized resources are provided in `*.properties` files as specified by the
`java.util.PropertyResourceBundle` standard class.
+However SIS does not use those resources files directly. Instead
`*.properties` files are transformed into binary files having
+the same filename but the `.utf` extension. This conversion is done for
efficiency, for convenience (the compiler applies the
+`java.text.MessageFormat` _doubled single quotes_ rule itself), and for
compile-time safety.
+
+In addition to generating the `*.utf` files, the resource compiler may modify
the `*.java` files having the same name than the
+resource files. For example given a set of `Vocabulary*.properties` files (one
for each supported language), the compiler will
+generate the corresponding `Vocabulary*.utf` files, then look for a
`Vocabulary.java` source file. If such source file is found
+and contains a public static inner class named `Keys`, then the compiler will
rewrite the constants declared in that inner class
+with the list of keys found in the `Vocabulary*.properties` files.
+
+Apache {{% SIS %}} uses a plugin in `buildSrc/` for processing resources.
+This plugin is used automatically by Gradle.
+
+
# History {#history}
The build system before Apache {{% SIS %}} 1.4 was Maven.
diff --git a/layouts/partials/menu.html b/layouts/partials/menu.html
index e9fd3953..80578e49 100644
--- a/layouts/partials/menu.html
+++ b/layouts/partials/menu.html
@@ -16,7 +16,6 @@
<ul class="dropdown-menu" aria-labelledby="menuDownload">
<li><a class="dropdown-item"
href="/downloads.html">Downloads</a></li>
<li><a class="dropdown-item" href="/source.html">Checkout
Sources</a></li>
- <li><a class="dropdown-item" href="/build.html">Build from
Sources</a></li>
<li><a class="dropdown-item" href="/epsg.html">EPSG Database</a></li>
</ul>
</li>
