| //// |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| //// |
| Development Environment |
| ======================= |
| |
| [[building-testing]] |
| Building and Testing |
| -------------------- |
| |
| TinkerPop requires `Java 1.8.0_40+` for proper building and proper operations. |
| |
| * Build Project: `mvn clean install` |
| ** Specify specific tests in a TinkerPop Suite to run with the `GREMLIN_TESTS` environment variable, along with the |
| Maven project list argument, e.g.: |
| + |
| ---- |
| export GREMLIN_TESTS='org.apache.tinkerpop.gremlin.process.traversal.step.map.PathTest$Traversals,org.apache.tinkerpop.gremlin.process.traversal.PathTest' |
| mvn -Dmaven.javadoc.skip=true --projects tinkergraph-gremlin test |
| ---- |
| ** Clean the `.groovy/grapes/org.apache.tinkerpop` directory on build: `mvn clean install -DcleanGrapes` |
| ** Turn off "heavy" logging in the "process" tests: `mvn clean install -DargLine="-DmuteTestLogs=true"` |
| ** The test suite for `neo4j-gremlin` is disabled by default - to turn it on: `mvn clean install -DincludeNeo4j` |
| * Regenerate test data (only necessary given changes to IO classes): `mvn clean install -Dio` from `tinkergraph-gremlin` directory |
| ** If there are changes to the Gryo format, it may be necessary to generate the Grateful Dead dataset from GraphSON (see `IoDataGenerationTest.shouldWriteGratefulDead`) |
| * Check license headers are present: `mvn apache-rat:check` |
| * Build AsciiDocs (Hadoop must be running and link:http://www.grymoire.com/Unix/Awk.html[awk] version `4.0.1` is required): `bin/process-docs.sh` |
| ** Build AsciiDocs (but don't evaluate code blocks): `bin/process-docs.sh --dryRun` |
| ** Build AsciiDocs (but don't evaluate code blocks in specific files): `bin/process-docs.sh --dryRun docs/src/reference/the-graph.asciidoc,docs/src/tutorial/getting-started,...` |
| ** Build AsciiDocs (but evaluate code blocks only in specific files): `bin/process-docs.sh --fullRun docs/src/reference/the-graph.asciidoc,docs/src/tutorial/getting-started,...` |
| ** Process a single AsciiDoc file: +pass:[docs/preprocessor/preprocess-file.sh `pwd`/gremlin-console/target/apache-gremlin-console-*-standalone "" "*" `pwd`/docs/src/xyz.asciidoc]+ |
| * Build JavaDocs: `mvn process-resources -Djavadoc` |
| * Check for Apache License headers: `mvn apache-rat:check` |
| * Check for newer dependencies: `mvn versions:display-dependency-updates` or `mvn versions:display-plugin-updates` |
| * Deploy JavaDocs/AsciiDocs: `bin/publish-docs.sh svn-username` |
| * Integration Tests: `mvn verify -DskipIntegrationTests=false` |
| ** Execute with the `-DincludeNeo4j` option to include transactional tests. |
| ** Execute with the `-DuseEpoll` option to try to use Netty native transport (works on Linux, but will fallback to Java NIO on other OS). |
| * Performance Tests: `mvn verify -DskipPerformanceTests=false` |
| * Benchmarks: `mvn verify -DskipBenchmarks=false` |
| |
| [[docker-integration]] |
| Docker Integration |
| ------------------ |
| |
| TinkerPop provides a shell script, that can start several build tasks within a Docker container. The |
| required Docker images will be built automatically if they don't exist yet. Thus the first invokation |
| of the Docker script is expected to take some time. |
| |
| The script can be found under `PROJECT_HOME/docker/build.sh`. The following tasks are currently |
| supported: |
| |
| * run standard test suite |
| * run integration tests |
| * build Java docs |
| * build user docs |
| |
| A list of command line options is provided by `docker/build.sh --help`. The container will install, |
| configure and start all required dependencies, such as Hadoop. |
| |
| If the container is used to generate the user docs, it will start a web server and show the URL that |
| is used to host the HTML docs. |
| |
| After finishing all tasks, the script will immediately destroy the container. |
| |
| IDE Setup with Intellij |
| ----------------------- |
| |
| This section refers specifically to setup within Intellij. TinkerPop has a module called `gremlin-shaded` which |
| contains shaded dependencies for some libraries that are widely used and tend to introduce conflicts. To ensure |
| that Intellij properly interprets this module after importing the Maven `pom.xml` perform the following steps: |
| |
| . Build `gremlin-shaded` from the command line with `mvn clean install`. |
| . Right-click on the `gremlin-shaded` module in the project viewer of Intellij and select "Remove module". |
| . In the "Maven Projects" Tool window and click the tool button for "Reimport All Maven projects" (go to |
| `View | Tool Windows | Maven Projects` on the main menu if this panel is not activated). |
| . At this point it should be possible to compile and run the tests within Intellij, but in the worst case, use |
| `File | Invalidate Caches/Restart` to ensure that indices properly rebuild. |
| |
| Note that it maybe be necessary to re-execute these steps if the `gremlin-shaded` `pom.xml` is ever updated. |
| |
| Developers working on the `neo4j-gremlin` module should enabled the `include-neo4j` Maven profile in Intellij. |
| This will ensure that tests will properly execute within the IDE. |
| |
| If Intellij complains about "duplicate sources" for the Groovy files when attempting to compile/run tests, then |
| install the link:http://plugins.jetbrains.com/plugin/7442?pr=idea[GMavenPlus Intellij plugin]. |