Change swimming pool tag
[potlatch2.git] / README.md
1 # Potlatch 2.0 - OpenStreetMap editor in ActionScript 3
2
3 Potlatch 2.0 is the fourth OpenStreetMap online editor (after two Java applets and Potlatch 1, and before iD). It's written in ActionScript 3 and requires a Flash Player.
4
5 ## What you'll need
6
7 * Apache Flex SDK - download the installer at https://flex.apache.org/installer.html
8 * AS3 docs - http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/
9 * Flash debug player - http://www.adobe.com/support/flashplayer/debug_downloads.html
10
11 The Flash debug player is essential to see errors as and when they occur.
12
13 You'll only need OSM Rails port installed on your local machine if you are doing hard-core server-communication coding. Generally you can use the dev server at api06.dev.openstreetmap.org for development and testing.
14
15 ## Compiling during development
16
17 * `fcsh`
18   - launches the Flex Compiler SHell -- stops the compiler having to
19     bootstrap itself each time you invoke it. You don't need this, but it
20     does make things slightly faster (about a second a shot for me)
21 * `mxmlc -load-config+=debug-config.xml potlatch2.mxml`
22   - compile potlatch2 in debug configuration -- build is incremental so you
23     can run it again and mxmlc will only compile changes. Output has debug
24     enabled along with decent stack traces.
25     (you can substitute halcyon_viewer.as in the above to compile that)
26 * `compile 1`
27   - when using fcsh recompile the first command. (Incremental recompiling does not work on Java 8, but 6 or 7 are fine.)
28
29 If you have rlwrap on your system, use `rlwrap fcsh` so that command-line history will work within fcsh.
30
31 Flash's security model will not allow you to make calls from localhost to the internet. Either use 127.0.0.1 instead; or run `resources/server.py` to launch a local server, then go to http://localhost:3333/potlatch2.html to get started (or if you're already running e.g. Apache locally, feel free to use that instead.) Alternatively, you can update your global Flash security settings to "always trust files" in your local dev area.
32
33 If you are testing against a local copy of openstreetmap-website, you will need to add an OAuth application by going to `http://rails-port.local/user/<username>/oauth_clients/new`. Enter `Potlatch 2 (local)` as the name and `http://localhost:3333/resources/potlatch2.html` as the application URL, and then update resources/potlatch2.html replacing the domains.
34
35 ## Compiling using ant
36
37 1. Copy the properties template file: `cp build.properties.template build.properties`
38 2. Edit the FLEX_HOME variable in build.properties: e.g. `FLEX_HOME=c:/flex_sdk/4.5.0.20967`
39 3. `ant` to compile in debug configuration, putting the result at resources/potlatch2.swf
40
41 You can also `ant release` to compile in release configuration; `ant halcyon` to compile the Halcyon rendering engine as a standalone viewer; `ant docs` to create class documentation (in resources/docs) using asdoc; `ant test` to run the (few) unit tests using flexunit.
42
43 `ant debug-no-locales` and `ant release-no-locales` are quicker as they skip the translation steps. You may need to tell ant to use more memory, by typing export ANT_OPTS="-Xms768m -Xmx1024m -XX:MaxPermSize=768m -XX:ReservedCodeCacheSize=512m" beforehand (you can put this in your .profile).
44
45 ## Compiling with Flex Builder
46
47 If you happen to have Adobe Flex Builder 3/Flash Builder 4, you can create a project and import files into it. See http://wiki.openstreetmap.org/wiki/Potlatch_2/Developer_Documentation for details.
48
49 ## Thank you
50
51 Many icons used in halcyon/potlatch2 are based on the awesome CC0-licensed SJJB icons project. http://www.sjjb.co.uk/mapicons/
52
53 Thanks to Dave Stubbs, Andy Allan, Steve Bennett and everyone else who contributed to Potlatch 2 during its heyday. 
54
55 Richard Fairhurst / @richardf