GeoGig for developers ===================== This page includes information for developers wanting to work with GeoGig. Building --------- To build GeoGig from source, follow these steps: - Clone the GeoGig source code repository. To do so, create a new folder where you want the GeoGig source code to be kept, open a console and move to that folder. Now type the following. :: $git clone https://github.com/locationtech/geogig.git - Install the software needed to build GeoGig (you can skip one or both of the steps below in case you have Java and/or Maven already installed in your system) - Download and install a Java Development Kit (JDK) from the `Oracle Java website `_. - Download and configure `Maven `_. - Move to the ``src/parent`` folder under the folder where you have cloned the GeoGig source code, and type the following. :: $mvn clean install - GeoGig should now be built, and scripts ready to be run should be available in the ``src/cli-app/target/geogig/bin`` folder. Add that folders to your ``PATH`` environment variable, so your system can find it and you can call GeoGig from the console. - To test that GeoGig is ready to be used, open a console and type ``geogig help``. You should see a list of available commands like the one shown below. :: usage: geogig [] The most commonly used geogig commands are: --help Print this help message, or provide a command name to get help for add Add features to the staging area apply Apply a patch to the current working tree branch List, create, or delete branches cat Provide content of an element in the repository checkout Checkout a branch or paths to the working tree cherry-pick Apply the changes introduced by existing commits clean Deletes untracked features from working tree clone Clone a repository into a new directory commit Record staged changes to the repository config Get and set repository or global options conflicts Shows existing conflicts diff Show changes between commits, commit and working tree, etc [...] Working with eclipse --------------------- To work with the Eclipse IDE, follow these steps. - Move to the ``src/parent`` folder and type the following to build the corresponding eclipse projects: :: $mvn eclipse:eclipse - Open Eclipse and create a new workspace by selecting *File->Switch Workspace->Other...* menu and choosing an empty directory - Select the *File->Import...* menu and then select "Existing projects from workspace". You will see the dialog shown below .. figure:: ../img/import_eclipse.png - Select *Maven->Existing Maven Projects* and click on *Next* - In the *Select root directory* field, select the ``src`` folder where the GeoGig source code can be found (which now will also contain the Eclipse projects). The list of projects in the *Projects* field will be populated. - Click on *Finish* and all of GeoGig projects will be added to your workspace. To handle maven projects directly from Eclipse, you can use the `m2eclipse `_ plugin. Once your workspace contains the GeoGig source code, configure it following these steps. - Open the preferences dialog (*Eclipse->Preferences*) and in the left part, select the *Java->Code Style->Formatter* entry. .. figure:: ../img/formatter.png - Press the *Import* button and import the GeoGig formatting rules that are found at ``build/eclipse/formatter.xml``. Set ``GeoGig`` as the current active profile. - If you use the auto-formatting on save option, make sure that only edited lines are formatted. .. figure:: ../img/autoformat_save.png Programming guide ----------------- Here are some notes to help you get introduced in programming GeoGig - GeoGig makes extensive use of the `Google Guava library `_. Check its documentation and use it when possible, as it contains many valuable tools that will increase code readability. Of particular relevance are the usage of `preconditions `_, of utilities to deal with `collections `_ and of the ``Optional`` class to `avoid null references `_. Make sure you check the above links to get familiar with those elements. - Tests are written using the Junit framework. Online tests that require a GeoGig endpoint, are available using ``mvn -Ponline``. - Cobertura is configured for a test coverage report: :: mvn cobertura:cobertura open target/site/cobertura/index.html - Functional tests are available for the command-line interface. GeoGig uses the `cucumber-jvm `_ framework for functional testing. The ``RunFunctionalTest`` class is a JUnit Runner that will run all cucumber functional tests. To run a single test from Eclipse, you can install the `cukes-jvm-eclipse plugin `_. Once installed, you can right click on functional test files (which have the ``.feature`` extension) and run them individually. More information about running cucumber tests from eclipse can be found `here `_. Technical documentation ------------------------- Technical documentation is available in the ``docs/technical`` folder. It contains mostly descriptions of the mechanisms used by some GeoGig core operations.