Get and Build the Source Code
Setup Mercurial (optional):
Config file $Hg Install Dir\Mercurial.ini on Windows or
Enhance the default configuration, using GIT diff and enable default plugin avoid different line breaks in the source.
[ui] username = your Name yourLoginName@odftoolkit.org ;merge = your-merge-program (or internal:merge)
[diff] git = 1
[defaults] diff=-p -U 8
# Enables mercurial EOL extension for line break handling
# See http://mercurial.selenic.com/wiki/EolExtension (bundled since 1.5.4)
# It'll remove unknown files and empty directories by default.
# Usually you call 'hg update -C' and 'hg purge' in sequence
# See http://mercurial.selenic.com/wiki/PurgeExtension (bundled)
# Converts mixed line ending within a file to LF (Unix) format
# before adding the file to the source repository
# See http://mercurial.selenic.com/wiki/EolExtension
only-consistent = False
Get the ODFDOM source code from the odfdom~developer Mercurial repository. Please see below for a short introduction to using Mercurial on odftoolkit.org. There's also a more general help on how to use source control systems on odftoolkit.org. The command
hg clone https://odftoolkit.org/hg/odfdom~developer will download the repository into a new directory.
Please note that by this you'll get the latest changeset. If you for example want stable release 0.8.6, you may want to use
hg clone https://odftoolkit.org/hg/odfdom~developer -r v0.8.6
ODFDOM Developers however always work on the latest changeset.
Now get and install Apache Maven. On command line test your installation with "mvn -v".
If Maven is correctly installed, change into the project directory and build with command "mvn".
Set up ODFDOM Development Environment
Using Eclipse IDE
You can also set up your own ODFDOM development environment in Eclipse.
Using Netbeans IDE
To establish your own ODFDOM development environment:
Since Netbeans 6.1 the Mercurial plugin is part of the IDE, which help you to track the changes being made and ease providing patches. Select in the menu among 'Versioning' the desired Mercurial commands.
After the commitment of your changed files, you need to pull the latest updates from the server, perhaps merge them with your changes and finally push your changes to the repository using in the menu Versioning->Mercurial->Share->Push Other...
Command Line Tools
Mercurial is the version control system used for ODFDOM development.
Here a list of the most frequently used commands:
// Get source code into a new local repository hg clone https://odftoolkit.org/hg/odfdom~developer [new folder name] // See if there are updates hg in // See if you have local changes hg status // If there are no local changes: Update hg pull hg update // Display the latest 3 entries of the revision history hg log -l 3 // Display only the latest entry of the revision history hg tip // Register all locally created or deleted files. // Please carefully check the output of "hg status" first hg addremove // Safe alternatives hg addIn case you do changes for a bug or feature request, please export them as a patch and attach them to the bug's entry on the issue list. If there's no such entry, please create one first.
hg remove hg remove -A
// Commit your changes locally and display their revision number hg commit -A -u "your Name" -m "#bug XY# Description of changes" hg tip // Export your locally committed changes as patch hg export -a -g -o ../myChanges.patch
// Import changes into your local repository hg import --no-commit ../someFile.patch // Get help hg help // Get help about a special command hg help hg help export hg help addremove ...
That way others will review your patch for you. If everything is ok, the reviewer will push your changes to the global repository. This procedure is the same for all developers and is meant to keep up code quality.
Maven is the build manager used for ODFDOM development.
// Build the project and create target/odfdom.jar mvn // Workaround: Ignore failed test when building mvn -Dmaven.test.failure.ignore=true clean install // Create javadoc mvn javadoc:javadoc // Generate DOM layer elements and attributes from RelaxNG mvn clean test -P codegen // Generate code coverage documentation in //
/target/site/cobertura/index.html // see http://mojo.codehaus.org/cobertura-maven-plugin/ mvn cobertura:cobertura
Coding Guidelines ODFDOM take advantage of the existing Java Coding Guidelines.
Aside of the Naming Convention of Java Coding Guideline, we use an 'm' as prefix for member object variables, e.g. "mParentDocument". Note: There should be NO datatype prefix being used as 'i', 's', etc.
Source Code Format
Although Maven may support source code formatting it has not yet been enabled. Instead the automated formatting via the IDE is used (e.g. by Netbeans via the context menu - Format).
To allow a customized indentation within the IDE based on the user's taste, the indent shall be done using TABs. For instance, Svante uses a 4 whitespace indent by TABs configured within Netbeans.
There have been recently problems with merging sources using Mercurial when working with different platforms (windows/unix). For this reason, some additional Mercurial configuration shall be used to unify the interal line feed handling.
Current and Future Work
Especially the convenient layer will grow on demand. As ODFDOM should be the base of many future ODF projects, a high quality is desired. Therefore automatic tests are obligatory for all new sources of the Java reference implementation.
The development is being discussed on the dev mailing list.
While we still plan to deliver quarterly results, we created some large feature groups/headlines for the upcoming versions
In general when building a layered API, it seemed reasonable to start from the button to base higher APIs on the stable lower layers:
Please see also for open tasks.
ODFDOM Code Generator
The ODFDOM Code Generator is used to generate the core Classes for ODFDOM which are a typed mapping of the ODF elements on real Java Classes. For the future we also plan to generate ODFDOM e.g. C# ( .NET ) for other programming languages with this generator. Take a look at this page ODFDOM Code Generator to see how the generator works in general (will be updated soon). We are moving toward treating the code generator as a separate component. The repository http://odftoolkit.org/hg/odfdom~relaxng2template is the new home of the code generator. It may move to its own project on this site at some point.
Other Useful Pages