Potlatch 2/Developer Documentation

Feedback and bugs

• You can view the current list of potlatch2 bugs on trac.
• If you find a bug involving data loss or corruption, or a serious problem that would prevent you from using Potlatch 2, please report it on trac with the component "potlatch 2"
• If you have any other bug, please report it on trac with the component "potlatch 2"
• If there's something Potlatch 2 doesn't do which is essential to your mapping enjoyment, please report it on the Suggested enhancements page.
• How to submit extra detailed bug reports (more complicated but very very helpful).
• For historical interest, Closed issues.

Get involved

There's lots of ways to get involved with Potlatch 2 development, very few of which need any coding skills.

• Write useful bug reports when you find problems - see above
• Improve the user documentation on this wiki
• Develop custom MapCSS styles, and improve the ones we have (no compiling required)
• Develop custom Preset files, and improve the ones we have (no compiling required)
• Improve the developer API documentation
• Expand our suite of unit tests
• Hunt down and fix the bugs listed on trac
• Add new features!

Potlatch 2 is written in ActionScript 3 using the open-source Flex framework. We'd love it if you were to get involved in development.

The source is stored in git, we no longer use svn. Subscribe to the potlatch-dev mailing list to get in touch with the developers.

Read more on the OpenGeoData blog post and see a presentation from WhereCamp.EU 2010.

Getting started

How to compile and run

Download Adobe Flex from over here. You want version 4.5.1 It doesn't matter if you get the Open Source Flex SDK or Adobe Flex SDK (proprietary) versions though the open is smaller.

Make sure you have git installed. Then:

 git clone http://git.openstreetmap.org/potlatch2.git

Next, copy the build template to something sane:

 cp build.properties.template build.properties

You want to change the Flex home to where you downloaded and extracted the flex SDK. So edit the build.properties file and change it to something like this:

 FLEX_HOME=c:/flex_sdk/4.5.1.21328

Make sure you have ant installed and then run it:

 ant

If everything goes to plan you will start to see debug output as ant builds potlatch

 Buildfile: /home/steve/software/potlatch2/build.xml
   git-buildnumber:
   svn-buildnumber:
   buildLocales:
     [echo] Building Localization .swf's
     [mxmlc] Loading configuration file /home/steve/Desktop/flex_sdk_3.5.0.12683_mpl/frameworks/flex-config.xml

Next, run a webserver to see things:

 cd resources
 ./server.rb

Then head over to

 http://localhost:3333/potlatch2.html

and with luck you'll see your compiled copy of P2. You might be asked to go confirm a account on the test server so you can edit things, and you should do so (it's not the same as the main osm.org server).

More Compile Commands

Compiling Halcyon as standalone viewer:

 ant halcyon

You can create class documentation (in resources/docs) using asdoc

 ant docs

You can create and run the unit tests (not that there are that many) using flexunit

 ant test

You can clean out the generated files from the project by running:

 ant clean

If you're using Mac OS X, you may need to tell ant to use more memory, by typing export ANT_OPTS=-Xmx500M beforehand (you can put this in your .profile).

Would you like to know more?

More details are over here but please start moving documentation here so that people can actually read and edit it.

ActionScript documentation (ASDoc)

• http://random.dev.openstreetmap.org/potlatch2/docs/

Documentation

• Overview of the directory structure, what to find where.
• How the layering system works.
• How the Undo system works.
• A quick intro to the git migration.
• Editing the tagging presets (map features).
• How to make a release
• Flex 4 todo
• /Compiling with Flex Builder (optional)

Sending patches

Yay!

We like patches in any way, but if you're sending a pull request, please send it to systemed on github ([1]) aka Richard, rather than git.openstreetmap.org or the openstreetmap account on github. Thanks.

A note on opensourceness

We get a lot of stick about Potlatch 2 not being open-source, so lets address that here.

• Potlatch 2 and Halcyon are open-source (WTFPL)
• They are written in ActionScript3.0, which is an open-source language
• They depend on the Flex libraries, which are open-source
• They depend on some other code libraries, which are all open-source
• The compiler, part of the Flex SDK, is open-source
• The build system uses Ant, which is open-source
• The test system uses Flexunit, which is open-source
• The documentation system uses ASDoc, which is open-source
• The translation system uses babelFx, which is open-source

However, there is no denying that what you end up with is a .swf file that, as of today, only plays on the closed-source Adobe Flash Player (v9 and v10). There are a number of open-source swf players available, but none of them is yet fully-featured enough to handle the needs of Potlatch 2.

• Gnash supports only the (old) AVM1 binaries. ActionScript3 compiles to AVM2 binaries. Gnash looks unlikely to support AVM2 in the near future, if ever.
• Lightspark is an AVM2-capable player, and is probably the most likely to support P2 in future. See our ticket with them on launchpad
• In the long term, Jangaroo and Falcon-JS may permit cross-compiling to JavaScript.

Also, Adobe have lots of non-open-source development toolkits, including the FlashBuilder/FlexBuilder IDE, expanded versions of the Flex SDK with more libraries, and so on. None of these are needed for P2 development, but I would say Adobe are deliberately unhelpful when you start poking around on their site.