Building PCGen

Building PCGen from the command line

This process uses the ANT tool, you need the following software packages:

• Java Development Kit (aka Java SDK or JDK). You should use the latest version (update) of the JDK 6.0 available for download from here. At the time of writing this was Java SE 6 Update 29. Java 7 will also work for the new UI, but no 1.7 specific features should be used in the code. Other JDKs might work, but no one has tried.
• Ant 1.7.0 (or later) from here. Ant is an all-Java replacement for make, and is fully cross-platform. Note: You will also need to download the jakarta-ant optional.jar file if using certain versions of Ant. See ANT section for further details
• If you wish to run the test suite you will need JUnit 3.6 from here.
• You will also need the latest version of the PCGen source code available from SVN. See Subversion Setup for details.

Open a command window and change to the root directory/folder where you installed the PCGen source code. There should be a file called build.xml there.

Type ant clean at the command prompt. This will make sure you have a clean start. Then run ant. This will build the pcgen.jar file. The jar file will be in ./bin. You can run pcgendev.bat or pcgendev.sh to run it or manually copy the jar file to the PCGen root directory.

NOTE

• If you get a "Could not create task of type: javacc" you need to ensure you have the jakarta-ant optional.jar file in the $ANT_HOME/lib directory. (You only need this for older versions of Ant).
• If you get a "Could not create task of type: junit" you need to copy the junit.jar file from the pcgen/libs directory to the $ANT_HOME/lib directory. (You only need this for older versions of Ant).

To generate the JavaDocs use ant docs, and for deployments you can use ant deploy, and finally ant all does all of the above (clean, build, docs, deploy), and ant complete does everything including a full testing cycle (which can take a while).

Typing the command

ant

will build the code and run a small selection of tests. Typing the command

ant dotest

will build the code and run the full test suite. Typing the command

ant reporttest

after running the tests will generate a test report. The xml result files are generated while running the tests, they can be found in ./code/build/test-results/xml/ after making the reporttest target, a browsable set of html reports can be found in ./code/build/rpt/test-results/

Using Eclipse to build PCGen

You can build PCGen from within Eclipse. You will need to do a little bit of setup first though:

1. Go to Window > Preferences, then Ant > Runtime then select Ant Home Entries under the Classpath tab.
2. Click Add Jars. Select the junit.jar under pcgen/lib.

Now you should be able to select the build.xml, right click and hit Run > Ant Build and it should work.

Running and debugging

1. Open the PCGen project.
2. Open the Run dialog by right-clicking on the PCGen project and selecting Run As > Run Configurations
3. Select the Java Application node.
4. Press the New button for a new configuration. Edit by field, thus:

Name -> PCGen

Main class -> pcgen.system.Main

VM arguments (Arguments tab) -> -Xmx1024M

1. Press Apply to save the configuration.
2. Press Run to start PCGen.

You can also run a single test by right clicking on the test and selecting Debug > JUnit Test. This is a great way to track through a bug too.

Using IDEA to build PCGen

You can build PCGen from within IDEA. You will need to do a little bit of setup first though:

1. Go to the Window > Tool Windows > Ant Build. Press the [+] button to add a build file.
2. Navigate to and select the build.xml Ant script in the root of the PCGen project tree. Press Ok.

You can now select any Ant target you wish. Particularly helpful are the build and fetch-data targets.

Running and debugging

NB - IDEA will build the software sufficient for running and debugging within the IDE automatically just by following these step. This is not the same as the build from the Building section, above, which builds the software suitable for command-line use.

1. Open the PCGen.ipr project file.
2. Get the Run/Debug Configurations dialog with Run > Edit Configurations from the menu bar.
3. Select the Application tab.
4. Press the [+] button for a new configuration. Edit by field, thus:

Name -> PCGen

Main class -> pcgen.system.Main

1. Uncheck Display settings before running/debugging.
2. Press Ok.

You can now run PCGen with the green right-pointing triangle on the toolbar and debug with the green right-facing beetle on a blue diamond. Or just use the Run menu.

Using Maven to build PCGen

See MAVEN