Documentation

Getting Started

README

The README file in the top level directory of the source code contains everything you need to get started: how to get the code in the first place, how to configure and build it, and how to use java-gnome as a library in your projects.

doc/examples/

While not a complete tutorials in themselves, we have a growing number of small example applications that ship with the source, including one for the complex TreeView / TreeModel API. See doc/examples/START for links to those that have been formatted for web viewing, but remember all the source code is always viewable online if you don't have a checkout handy. Just pull up the 'mainline' branch and navigate to doc/examples/. The same goes for the rest of the java-gnome code base; it's all there, including the sources for this website.

Tutorials

Tutorials to get people started and guides about how to use the more complex APIs are still a work in progress. They will start appearing on this website in the coming months.

API Documentation

doc/api/

We have put considerable effort into ensuring the java-gnome bindings are easily usable for people using IDEs like Eclipse, and a big part of that is having useful JavaDoc so that the help popups you get when you hover over a class or method helps to the programmer figure out what they need to do in that context.

The API documentation in the underlying GNOME libraries tends to be sparse and is very much in the reference style. That's great if you already know what you're doing and just need to look something up, but isn't much help if you are trying to figure out how to use a library in the first place. Because of our focus on approachability, we take a somewhat different approach. The API documentation in java-gnome is in a more conversational style and is squarely aimed at helping people learn GTK. Where possible we also include code snippets to help you understand how to use the APIs,

The API documentation is of course generated by javadoc when you build the source code and is located at doc/api/4.1/. The canonical public version of the JavaDoc is hosted here; you can link to it from your own JavaDoc if you like.

Contributing

java-gnome is an Open Source project, and as such is the sum of the contributions of the hackers who actually write the bindings code, the maintainers who take care of library's build system and do releases, the packagers downstream who make the software available in their distributions, and of course you, the developers using the library to write your applications. who send in bug reports and feedback.

HACKING

Providing complete coverage of the underlying GTK and GNOME libraries is a mammoth task and you are welcome to get involved!

java-gnome has been carefully designed to be extensible, maintainable, and above all easy to hack on. Like any large project, though, there are complexities and common practises that you will want to be on top of before trying to work on it yourself.

Anyone wishing to contribute to the java-gnome project is therefore advised to read the top level HACKING file before doing anything else. It provides instructions on how to checkout the source code in such a way that you can easily work on your own branches, tips on how to go about learning the internals of the bindings, and links to the style guide.

doc/design/

The source code contains considerable reference material about the background of the project, the design constraints which governed the re-engineering effort and discussion of the architecture we arrived at. Much of this documentation is made available here on this website, cunningly rendered into HTML form.

A good starting point is the doc/design/START file, which links to each of the other documents in that directory.

doc/style/

In order to meet our quality and approachability goals, we have put in place certain guidelines to help keep us co-ordinated and to minimize friction. If you'd like to ensure that code or documentation you might choose to send in will be accepted, please read the documents in the doc/style/ directory carefully. They are in essence an extension of the HACKING file and together with the design documentation tell you everything you need to know to be able to contribute to java-gnome.