= A Problem Has Occurred = Supremely short version: A firewall died, a server got rebooted, and things got out of whack. As a result, the original www.cache901.org site is temporarily out of commission, and all traffic is pointed here. We hope to bring the original back very shortly. In the meantime, downloads are available at http://code.google.com/p/cache901/ = Welcome To The Cache 901 Developer's Corner / Issue Tracker = Before anything else, I must remind people: This is open to everyone for reading. For writing, though, you will need to create an account in the developer's corner. [http://it.cache901.org/trac/register Register] for an account here, or by following the link in the upper right corner of the page, under the search box. Thank you. [[TOC]] == Prerequisites == As of right now, you need the following things to get started with developing Cache901. 1. A [http://www.selenic.com/mercurial/wiki/ Mercurial] VCS client. If you're on Windows, I recommend [http://bitbucket.org/tortoisehg/stable/downloads/ TortoiseHG]. If you're on Linux or Mac OSX, I personally use the command line, so have no recommendations as to which one to use. 2. [http://www.python.org/ Python] As of now, we are not working with either Python 2.6 or Python 3.0. Not until the [http://www.wxpython.org/ wxPython] toolkit starts supporting them will that even be an option. As such, [http://www.python.org/download/releases/2.5.2/ get the appropriate Python] for your platform, but keep the version to no higher than 2.5.x. 3. [http://www.wxpython.org/ wxPython] As of now, there is no maximum version of wxPython you may use. Do not use less than version 2.8.0.0, though, and it is recommended to [http://www.wxpython.org/download.php#binaries use the latest version], as one of the included tools (XRCEd) has better support for programming with wxPython. 4. An editor or IDE This is entirely personal choice. I happen to use [http://www.wingware.com/ Wingware's IDE], but there are [http://ask.slashdot.org/article.pl?sid=08/09/16/136219&from=rss others available], too, and some of them are quite good. 5. [http://www.cache901.org/developers-corner/python-gpsbabel python-gpsbabel] This is a required module for Cache901 after v0.2. 6. [http://pyserial.sourceforge.net/ PySerial] This is used to detect attached ports on the machine, and allow the user to specify which port to use to speak with the GPSr. 7. [http://www.sqlite.org/ SQLite] Comes with Python 2.5 and up, so you should not need to get anything. However, if your Python didn't come with it, here's where to get it. 8. [http://sourceforge.net/projects/pywin32/ PyWin32 Extensions] You only need this if you are on Windows. The PySerial module uses this module to scan for serial ports on that platform. If you are running an Intel or AMD CPU in 32 bit mode, it is recommended to get [http://psyco.sourceforge.net/ Psyco], a just in time compiler for Python. It does provide some noticeable performance improvements. Make sure to follow the directions from the respective websites for installing everything. Once you have everything installed, development is actually fairly easy. First, you will need to check out a local copy of the source code. You can do this by pointing your hg client at http://svn.cache901.org/ and running a checkout. == Tour of the Application == After installing the prerequisites, you just need a quick tour to show you where things are, and what they do. geocache901 and geocache901.py:: These two are copies of each other, and should never be different. If they are, this is a bug. In fact, I think I need to write a unit test for this, just to make sure they never get out of sync. Running either of these will start the program. py2app (the Mac application bundle maker) requires the main script end with .py, while the other platforms do not. Add in that I don't like having a main script on Linux which will end with ".py", and we get this result. However, both of these are extremely small. All they do is run the main() routine, located in cache901/app.py. cache901test:: We make extensive use of unit testing. All unit tests are automated, and placed in the test module. cache901test finds all cases in the test module and runs them. We don't have a reliable method for testing GUI code yet, but any non-GUI code should have automated unit tests in place. cache901/app.py:: This, too, is a fairly small file. It contains a class, Cache901App. It gets instantiated. The class shows a splash screen (since startup tends to take 2 to 3 seconds), and then instantiates the main window. The main window loads up the database, and is where all other action takes place. cache901/ui.py:: This is where the main window lives, and where the strangest stuff happens. The simple bits: You'll see a lot of "isinstance()" calls. These are hints for Wingware's IDE, so that it can provide proper autocompletion. The more magic stuff involves the next file: ui_xrc.py. The classes in ui.py are actually subclasses of classes in ui_xrc.py. The classes in ui_xrc.py are python implementations of the xrc file ui.xrc. cache901/ui.xrc:: This file defines all of the GUI resources in use throughout Cache901. Personally, I only edit it with XRCed, though other XRC editors do exist. Define the GUI in this file, test it out on a basic level. From there, hit the save button (which, due to ui.xcfg, will automatically generate ui.py and embed the XML and any graphics into it), and then subclass any new stuff by making new classes either in cache901/ui.py or in another file, and hook things together. == Unit Testing == Unit testing is critical to producing a quality program that will be maintainable for a long time to come. As such, we insist that all patches come with unit tests which will help us show what was broken and how it was fixed, or will show that the new functionality being added works as expected. We don't have an adequate test frame for the GUI classes, but we are working on it. Any suggestions on doing this bit of testing will be very welcome. For information on unit testing, I would recommend reading the following links: * [http://en.wikipedia.org/wiki/Unit_testing Unit Testing in General] * [http://docs.python.org/lib/module-unittest.html Python Unit Test Module] == Further Reading == Now, the hardest part of all this is determining what the valid methods for any given object are. For that, if you're using Wingware's IDE, autocompletion will help you out. If not, documentation exists at [http://www.wxpython.org/docs/api/ wxPython's site] (and a [http://wiki.wxpython.org/index.cgi/How_to_Learn_wxPython tutorial]), at the [http://docs.wxwidgets.org/stable/ wxWidgets] site, and a [http://www.informit.com/content/images/0131473816/downloads/0131473816_book.pdf downloadable PDF] at InformIT's site (which is a copy of the wxWidgets book). In addition, there is a book, [http://www.manning.com/rappin/ wxPython in Action], which can even be purchased as a PDF, that provides an excellent introduction to [http://www.wxpython.org/ wxPython]. All of these are thorough sources that can be used. Alternately, you can ask me, and I'll try to find an answer for you myself. My email is m(dot)pedersen(at)icelus(dot)org. All of that assumes that you were looking for wxWidgets documentation. If, however, you need quality Python documentation and tutorials, I have some additional recommendations: * [http://www.diveintopython.org/ Dive Into Python], a downloadable e-Book which does a good job with introduction * [http://www.python.org/doc/2.5.2/ Python Documentation], from the makers * [http://www.python.org/doc/2.5.2/tut/tut.html A Python tutorial], again from the makers That should get you a good start, I hope. Happy hacking, and email me with any questions or patches! == Starting Points For Using Trac == * TracGuide -- Built-in Documentation * [http://trac.edgewall.org/ The Trac project] -- Trac Open Source Project * [http://trac.edgewall.org/wiki/TracFaq Trac FAQ] -- Frequently Asked Questions * TracSupport -- Trac Support For a complete list of local wiki pages, see TitleIndex.