Penn TotalRecall Development

Open-source software is a collaborative effort. Please inform us if anything on this page is incorrect or out of date.

License

Penn TotalRecall is free and open-source software, released under the GNU General Public License, version 3. We encourage other groups to modify and improve the program. Please drop us a line if you're interested in developing TotalRecall or borrowing its code.

[Please note that at present we have one non-free dependency, so the resulting binaries are not fully free and open source. We are hoping to produce a completely free and open source in the future, although possibly only for Linux.]

Build guide

Please visit our build guide.

Development goals

Up-to-date documentation

Keeping documentation in step with the code base is an ongoing challenge. If you change the code, please make sure you are changing the documentation and propagating those changes to any other affected documentation. If you find out-of-date, inadequate, or misguided documentation, fix it!

This is doubly important for documentation on the wiki and documentation in build files.

Minimal dependencies

Introducing dependencies makes build automation, installation, and maintenance vastly more difficult. It also puts us in the position of relying on third-party open-source projects which may at any moment collapse due to lack of developer time/interest. Native dependencies are the worst, as they must constantly be updated for new operating system versions, changes in system libraries, etc. Plus they can crash the JVM.

When dependencies must be introduced they should ideally be pure Java and operate in a self-contained domain (i.e., not interacting with OS resources which may change over time). Since Java is strongly committed to reverse-compatibility we don't have to worry about the program breaking because of an obscure update to gcc or the release of a new operating system.

At this point there are only two dependencies that can potentially break:

• The FMOD Sound System. It is used extensively in major games so its stability and quality are assured. Updates are released regularly and their developers are responsive to questions on the FMOD forums. If we switch away from FMOD (to make TotalRecall totally FOSS), it will only involve re-implementing the pluggable sound system (edu.upenn.psych.memory.precisionplayer and edu.upenn.psych.memory.nativestatelessplayer).

• Java Native Access. This is the only case where we have preferred ease-of-use over our desire not to introduce dependencies. JNA is much easier to use than JNI and requires no boiler-plate code. It is also a high-quality library unlikely to break in the foreseeable future. If it does we can fall back on JNI.

Minimal developer overhead

Please be mindful that future developers and maintainers may not have the same skill set as you. So with future maintainers in mind it's best to minimize the number of exotic technologies needed to build or develop TotalRecall. At this point some knowledge of Java, Java2D/Swing, C, dynamic linking, Ant, GNU Make, and Git is already needed. Let's keep this list short by not needlessly adding C++, OpenGL, <your-favorite-technology>, etc.

Build automation

A brief look at our Ant build.xml reveals that we are not aiming for "zero dependencies" in our build toolchain. The build chain is designed to make it quick and easy to build/package/release TotalRecall for the many operating systems and architectures we support.

While the basic build process (i.e., what's needed to get the program running on your computer) should remain very simple, the full build system (e.g., creating installers, transferring to download site, etc.) can introduce dependencies and developer overhead as needed. To make build automation as simple as possible we try to include all the Ant task dependencies in the project. Ideally, someone with nothing more than their OS's standard build tools should be able to download our project and run all the ant tasks without having to chase down dependencies.

Dependencies and borrowed code

• FMOD Sound System, copyright © Firelight Technologies Pty, Ltd., 1994-2010. (FMOD non-commercial license).

• Java Native Access for binding the audio system to the JVM (LGPL).

• OpenMary TTS's signal processing library (BSD-like).

• OrangeExtensions as an open-source alternative to the official AppleJavaExtensions stubs jar (BSD).

• swing-keyboard-manager, a reusable keyboard shortcut manager for Java Swing (GPLv3, but developed in-house).

• Drag and drop support thanks to FileDrop (Public Domain).

Supported configurations

Note: Mac PowerPC is not officially supported, but the program is known to work on it.