sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1506171 - /sis/site/trunk/content/source.mdtext
Date Tue, 23 Jul 2013 17:25:59 GMT
Author: desruisseaux
Date: Tue Jul 23 17:25:59 2013
New Revision: 1506171

URL: http://svn.apache.org/r1506171
Log:
Ported the Maven 'Developping Apache SIS' page.

Modified:
    sis/site/trunk/content/source.mdtext

Modified: sis/site/trunk/content/source.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/source.mdtext?rev=1506171&r1=1506170&r2=1506171&view=diff
==============================================================================
--- sis/site/trunk/content/source.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/source.mdtext [UTF-8] Tue Jul 23 17:25:59 2013
@@ -31,20 +31,189 @@ For fetching the source code, choose one
     :::bash
     git clone git://git.apache.org/sis.git sis
 
+The remaining of this page provides tips SIS developers.
 
-Developers Guide
-================
+[TOC]
 
-Some coding practices:
+
+
+Opening Apache SIS in an IDE
+============================
+
+Different SIS branches are available depending on the target platforms (JDK6 versus JDK7,
or GeoAPI versions).
+The alternatives are listed in the [branches page](branches.html).
+This section documents how to checkout the trunk for development with Subversion,
+but the same instructions should work for any branch or for Git.
+
+While the primarily SIS build system is Maven, the project provides some IDE configuration
files for developers convenience.
+Before opening the project in an IDE, the source code needs to be downloaded from the source
repository
+and the project built at least once using Maven:
+
+    :::bash
+    svn checkout http://svn.apache.org/repos/asf/sis/trunk sis
+    cd sis
+    mvn install
+
+
+
+NetBeans
+--------
+
+NetBeans can open Maven projects natively. This is the recommended approach for casual working
in a small amount of SIS modules.
+For extensive work on Apache SIS or for work impacting many modules, it may be more convenient
and faster to open Apache SIS as a NetBeans project.
+Such pre-configured NetBeans project is available in the `ide-project/NetBeans` directory.
+This project will fetch dependencies directly from the `.m2/repository` local directory,
+and will refer to the resources `*.utf` files compiled by Maven in the `sis-*/target` directories.
+Consequently it is important to run `mvn install` before opening the project
+and after any change in the project dependencies or in the resources.
+
+Users can customize their project configuration by editing the `ide-project/NetBeans/nbproject/private/config.properties`
file.
+The `private` directory is excluded by the versioning system, so it okay to put user-specific
information there.
+For example in order to overwrite the default location of the local Maven repository and
to define a system property at execution time,
+one can use:
+
+    :::properties
+    maven.repository = /path/to/my/local/repository
+    run.jvmargs = -DmyProperty=myValue
+
+
+
+Eclipse
+-------
+
+Execute the saùe `svn checkout` to `mvn install` commands than in the NetBeans section,
+then execute the following steps:
+
+   * Execute `mvn eclipse:eclipse` on the command line.
+   * Open Eclipse in a new workspace.
+   * Go to _Eclipse_ → _Preferences_ → _General_ → _Workspace_.
+   * Change _Text file encoding_ to _Other: UTF-8_, press _Apply_, then _Ok_.
+   * Go to _File_ → _Import_ → _General_ → _Existing Projects in Workspace_.
+   * Choose the `sis` directory and import.
+
+
+
+Developing Apache SIS
+=====================
+
+Improving and extending SIS requires extensive knowledge of geographic information science,
+object oriented programming, the Java language, and of the library itself. Contributors should
+expect that they will need to learn a great deal before being able to become productive.
+However, the effort required to become productive should improve the contributor's understanding
+and knowledge of geographic information systems, of geodetic and geographic science, and
of
+effective computer programming.
+
+This document is expected to evolve as the SIS project develops its own mode of operation.
+
+
+
+Background Knowledge
+--------------------
+
+All contributors arrive to the project with different knowledge bases, some with scientific
+backgrounds, some with a background in computer science, and others with geographic backgrounds
+or even no training in geographic information science at all. By sharing the richness of
our
+individual backgrounds we have acquired a list of subjects which we consider critical to
fully
+understanding the SIS project. New contributors are highly encouraged to explore these
+areas if they have no or little knowledge of them.
+
+
+
+### Geographic Information Systems and Science
+
+While a background in the field is not required, it nonetheless proves exceedingly useful
along the way.
+GIS has developed its own language and has particular concerns which return frequently.
+Issues of spatial representation, data size, spatial scale, information workflows and other
topics
+arise frequently and are worth understanding.
+
+A good general introduction to the field is the book _Geographic Information Systems and
Science_
+by Paul A. Longley, Michael F. Goodchild, David J. Maguire and David W. Rhind published in
its
+second edition by John Wiley and Sons Ltd. in 2004.
+
+
+
+### The ISO/OGC Geospatial Model
+
+SIS builds on the standards developed through a collaboration between the International
+Organization for Standardization (ISO) and the Open Geospatial Consortium (OGC).
+Contributors to SIS should have at least a basic understanding of the model developed in
the
+ISO 19000 series of specifications, starting with the Abstract model and working through
the
+_Feature_ model. While the ISO specifications are sold, the OGC releases its own, essentially
+identical versions of standards which have evolved from the collaboration. The OGC specifications
+are available for the [OGC standards and specification][standards] page.
+
+As time progresses, we hope to develop documentation material to introduce the ISO 19000
specification series.
+
+
+
+### Object-Oriented Programming in Java
+
+SIS is a library designed to be used by other programmers. To play this role effectively,
+SIS must consider the various ways that users can reuse Java code: not only through object
+instantiation and method calls but also through inheritance. SIS pays special attention to
+accessibility constraints ensuring that only the classes and methods which are offered for
+use are publicly accessible and that these methods are fully and correctly documented in
javadoc.
+
+Contributors are highly recommended to read the book _Effective Java_ by Joshua Block, published
+in its second edition by Addison-Wesley in 2008. The book explains the importance of certain
+elements in the Java language and discusses subtleties of the language and its use.
+Most importantly, the book reveals the full scope a programmer must consider when developing
a code library.
+
+
+
+### Mathematical Background
+
+SIS frequently deals with complex calculations using relatively simple mathematics of
+trigonometry and matrix algebra. The coordinate operations of the Referencing modules involve
+trigonometric transformations on a flattened ellipsoid of rotation, the image transformations
in
+the Coverage modules and in the Rendering system involve extensive use of Affine transforms,
and
+the Analytic modules often use their own mathematical operations.
+These mathematics cannot be simplified — they reflect the richness of the world around
us.
+
+Affine transformations are not particularly complex but critically important both to the
+geo-referencing operations of the Referencing modules and to the image transformations of
the
+Coverage modules. Affines transform coordinates through translation, scaling, rotations,
and
+shear, though this latter component is used infrequently in the library. Mathematically,
+affine transformations are usually applied as a matrix operation applied to a coordinate
vector.
+There are numerous introductions to affine transformations available on the World Wide Web
since
+the concept is central to all graphics programming.
+
+
+
+### The GeoAPI Interfaces
+
+SIS is build partially as an implementation of the GeoAPI interfaces. GeoAPI defines a set
+of objects offering particular methods thereby providing an interpretation of the ISO/OGC
+standards in the Java language. GeoAPI therefore defines the core of the model implemented
+by Apache SIS.
+
+GeoAPI can most easily be learned by exploring the [GeoAPI Javadoc][geoapi].
+
+
+
+### The SIS library modules
+
+Contributors should gain a basic understanding of the core library including the separation
into
+modules, the functionality available in the base module, and the functioning of the modules
of interest.
+
+
+
+Some coding practices
+=====================
 
 * License Header: Always add the current ASF license header as described in [ASF Source Header][srcheaders].
-* Trailing Whitespaces: Remove all trailing whitespaces. Eclipse users can use Source->Cleanup
option to accomplish this.
+* Trailing Whitespaces: Remove all trailing whitespaces. Eclipse users can use Source-_Cleanup
option to accomplish this.
 * Indentation: Use 4 space indents (except for XML files) and never use tabs!
   Use 2 space indents for XML files, because ISO/OGC XML schemas tend to have a very deep
structure.
 * Line wrapping: Use 120-column line width for Java code and Javadoc.
 
 
+*[ISO]: International Organization for Standardization
+*[OGC]: Open Geospatial Consortium
+
 [viewvc]:     http://svn.apache.org/viewvc/sis/
 [subversion]: http://subversion.apache.org
 [git]:        http://git-scm.com
 [srcheaders]: http://www.apache.org/legal/src-headers.html
+[standards]:  http://www.opengeospatial.org/standards
+[geoapi]:     http://www.geoapi.org/3.0/javadoc/index.html



Mime
View raw message