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.
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.
How to compile and run
Make sure you have git installed. Then:
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:
Make sure you have ant installed and then run it:
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_184.108.40.20683_mpl/frameworks/flex-config.xml
Next, run a webserver to see things:
cd resources ./server.rb
Then head over to
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:
You can create class documentation (in resources/docs) using asdoc
You can create and run the unit tests (not that there are that many) using flexunit
You can clean out the generated files from the project by running:
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)
- 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)
We like patches in any way, but if you're sending a pull request, please send it to systemed on github () 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
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.