Difference between revisions of "TotalRecall Development"

From Computational Memory Lab
Jump to: navigation, search
 
(65 intermediate revisions by 6 users not shown)
Line 1: Line 1:
__NOTOC__
+
'''Open-source software is a collaborative effort. Please inform us if anything on this page is incorrect or out of date.'''
<!-- #acl yuvi:read,write Known:read -->
+
  
<<html(<h1>Penn [[TotalRecall]] Development</h1>)>>
+
== License ==
 +
[[TotalRecall|Penn TotalRecall]] is free and open-source software, released under the [http://www.gnu.org/licenses/gpl-3.0.txt 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.
  
<<[[TableOfContents]](3)>>
+
[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.]
  
'''Open-source software is a collaborative effort. PLEASE inform us if anything on this page is incorrect or out of date.'''
+
== Build guide ==
 +
Please visit our [[TotalRecall_Build|build guide]].
  
= License =
+
== Development goals ==
TotalRecall is free and open-source software, released under the [http://www.gnu.org/licenses/gpl-3.0.txt 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 working to produce a completely free and open source version in the near future.]
+
=== 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!
  
= User interface goals =
+
This is doubly important for documentation on the wiki and documentation in build files.
  
= Development goals =
+
=== 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.
  
== Zero dependencies ==
+
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.
This is not 100% achievable given the poor quality of Oracle's Java Sound implementation and the lack of signal processing in the standard libraries. However this goal serves to remind that introducing dependencies makes build automation, installation, and maintenance vastly more difficult.  
+
  
When dependencies must be introduced they should be pure Java packaged nicely into jars. 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.
  
At this point there are only two dependencies that can potentially break: the FMOD Sound System and the Java Native Access jar used to bind FMOD to the JVM. Both were selected because they are extremely high-quality and unlikely to stop working in the forseeable future. However, just to be safe, the sound system (`edu.upenn.psych.memory.precisionplayer` and `edu.upenn.psych.memory.nativestatelessplayer`) are designed in a pluggable way that allows re-implementation of the audio system without changing the program. If JNA ceases to work we can always fall back to 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.
  
== Minimum developer overhead ==
+
=== Build automation ===
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, C, Java2D/Swing, Ant, and GNU Make is already needed. Let's keep this list short by not needlessly adding C++, OpenGL, <your-favorite-technology>, etc.
+
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.  
  
== Build automation ==
+
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.
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 simple, the full build system (e.g., creating installers, transferring to download site, etc.) can introduce dependencies and developer overhead as needed.
+
  
= Dependencies and borrowed code =
+
== Dependencies and borrowed code ==
  
 
* [http://fmod.org/ FMOD Sound System], copyright © Firelight Technologies Pty, Ltd., 1994-2010. (FMOD non-commercial license).
 
* [http://fmod.org/ FMOD Sound System], copyright © Firelight Technologies Pty, Ltd., 1994-2010. (FMOD non-commercial license).
 +
* [http://jna.dev.java.net/ Java Native Access] for binding the audio system to the JVM (LGPL).
 
* [http://mary.dfki.de/ OpenMary TTS]'s signal processing library (BSD-like).
 
* [http://mary.dfki.de/ OpenMary TTS]'s signal processing library (BSD-like).
 +
* [http://ymasory.github.com/OrangeExtensions/ OrangeExtensions] as an open-source alternative to the official [[AppleJavaExtensions]] stubs jar (BSD).
 +
* [http://github.com/memlab/swing-shortcut-manager swing-keyboard-manager], a reusable keyboard shortcut manager for Java Swing (GPLv3, but developed in-house).
 
* Drag and drop support thanks to [http://iharder.sourceforge.net/current/java/filedrop/ FileDrop] (Public Domain).
 
* Drag and drop support thanks to [http://iharder.sourceforge.net/current/java/filedrop/ FileDrop] (Public Domain).
* Apple Java Extensions [http://developer.apple.com/mac/library/samplecode/AppleJavaExtensions/ wrapper] (BSD-like, but no source provided).
 
  
= Supported configurations =
+
== Supported configurations ==
  
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
Line 43: Line 48:
 
| '''Java versions'''
 
| '''Java versions'''
 
|-
 
|-
| Mac OS 10.6 (64-bit)
+
| Mac OS 10.6 (32/64-bit)
 
| Java 6
 
| Java 6
 
|-
 
|-
Line 49: Line 54:
 
| Java 5, 6
 
| Java 5, 6
 
|-
 
|-
| K/Ubuntu Linux 10.11 (32/64-bit)
+
| K/Ubuntu Linux 10.04 LTS (32/64-bit)
 
| Java 6
 
| Java 6
 
|-
 
|-
Line 63: Line 68:
  
 
Note: Mac PowerPC is not officially supported, but the program is known to work on it.
 
Note: Mac PowerPC is not officially supported, but the program is known to work on it.
 +
[[Category:TotalRecall]]

Latest revision as of 15:34, 29 October 2012

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

Supported configurations

Operating System Java versions
Mac OS 10.6 (32/64-bit) Java 6
Mac OS 10.5 (32/64-bit) Java 5, 6
K/Ubuntu Linux 10.04 LTS (32/64-bit) Java 6
Windows 7 (32/64-bit) Java 6
Windows Vista (32/64-bit) Java 5, 6
Windows XP (32-bit) Java 5, 6

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