Building the Library

Building from source code

The general command line to build PDDL4J from source code is as follow:

./gradlew build [options]
Options are:

  • -PnoCheckStyle to skip checkstyle verification

  • -PnoTest to tests

Note

To speed up the compilation of PDDL4, we recommend not running tests and style checks.

The command line to build PDDL4J without test and checkstyle verification is:

./gradlew build -PnoCheckStyle -PnoTest
The different build stages are the following:

  1. Compile Javacc (used to generate the parser)

  2. Compile Java

  3. Generate jar file

  4. Checkstyle Main (automate the process of checking Java main code), report in build/reports/checkstyle/main.xml

  5. Checkstyle Test (automate the process of checking Java test code), report in build/reports/checkstyle/test.xml

  6. Test (use JUnit testing framework to test PDDL4J functions), report in build/test-results/test

Creating a jar of the library

To create a jar of the PDDL4J library with all dependency libraries just use the command line:

./gradlew jar

The jar generated is located in the directory ./build/libs/pddl4j-X.X.jar where X.X is the version of PDDL4J. If the library is not build, the library is built before. The libraries include in the jar are :

  • Log4j used for logging;

  • JUnit used for unit tests;

  • Picocli to deal with planners command line.

  • JOL to analyze object layout schemes in JVMs.

Generating the Java documentation

To generate the java documentation of the library use the following command line:

./gradlew javadoc

To access to the documentation generated open the file ./build/docs/javadoc/index-all.html.

Generating the BNF of the parser

To generate the BNF (Backus–Naur form) of the PDDL language accepted by the parser use the following command line:

./gradlew jjdoc

To access to the documentation generated open the file ./build/docs/PDDL4J_BNF/lexer.html.

Generating the documentation

To generate the documentation just run the command line:

./gradlew site

To access to the documentation generated open the file ./build/docs/site/index.html.

Note

The documentation is generated using Sphinx with readthedocs using reStructuredText. The source code of the documentation is available in ./docs.

Running JUnit Tests

JUnit is a unit testing framework for the Java programming language. JUnit has been important in the development of test-driven development, and is one of the unit testing frameworks.

As a developer, it is important to include unit tests in your program to ensure that the functions/methods/algorithms return the expected results. In PDDL4J, unit tests are included to test the parser, the search strategies and planners with IPC benchmarks. To run all these tests, use the following command:

./gradlew test

The reports containing the results of JUnit tests are available in ./build/test-results/test/ folder.

Note

The execution of the tests is very time consuming. All planners are tested in several configurations on all IPC benchmarks they can handle. A search time is allocated to each problem of each domain. This time is usually set at 10 seconds. As soon as the planner fails to solve a problem within the time limit, the test procedure stops and checks whether the plans found are valid before finally moving on to the next domain and set of problems. For PDDL problems the plan validator used is VAL. For HDDL problems the plan validator used is Panda. Both plan validator are used in the international planning competition.

Warning

The planners JUnit tests will fail on windows os. The plan validators used are only available for linux or mac.

Checking source code convention

PDDL4J uses Checkstyle to check code source convention of the project. Checkstyle is a development tool to help programmers write Java code that adheres to a coding standard. It automates the process of checking Java code to spare humans of this boring (but important) task. This makes it ideal for projects that want to enforce a coding standard.

The different programming rules are defined in the ./checkstyle.xml file located in the ./config/checkstyle/ folder. A task has also been added in the ./build.gradle configuration file.

Thus, when building PDDL4J, a report containing the various errors will automatically be generated allowing the developers to correct his/her code before committing it. The generated report is located in ./build/report/checkstyle/ folder.

To run only checkstyle on the PDDL4J source code, use the following command line:

./gradlew checkstyleMain

It is also possible to run checkstyle on the source code of the JUnit tests:

./gradlew checkstyleTest

It is possible to disable code analysis with Checkstyle by passing the following parameter to Gradle:

./gradlew build -PnoCheckStyle