README.txt

   1 == Halcyon and Potlatch 2.0 - ActionScript 3 renderer and editor ==
   2
   3 Potlatch 2.0 is the new version of the OpenStreetMap online editor.
   4
   5 Halcyon is its rendering engine. It's rules-based (like, say, Mapnik) and does dotted lines, text on a path, casing, icons for POIs, all of that.
   6
   7 Both are written in ActionScript 3. Potlatch 2.0 additionally uses the Flex framework.
   8
   9 Many icons used in halcyon/potlatch2 are based on the awesome CC0-licensed SJJB icons project. http://www.sjjb.co.uk/mapicons/
  10
  11 === What you'll need ===
  12
  13 * Flex SDK 3.4 or 3.5
  14 ** Product page: http://www.adobe.com/products/flex/
  15 ** Flex 3 Download page: http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+3 (free, OS X/Windows/Linux)
  16 * AS3 docs - http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/
  17 * Flash debug player - http://www.adobe.com/support/flashplayer/downloads.html
  18 * Basically you might as well just sell your soul to Adobe
  19 * Ant
  20
  21 ***Do not use FlexSDK <= 3.3 or > 4***. There are compatibility errors with version 4, and 3.3
  22 and earlier have this bug: http://bugs.adobe.com/jira/browse/SDK-16705 which is a major issue for the
  23 tag editors.
  24
  25 If you happen to have Adobe Flex Builder 3/Flash Builder 4, you can create a project and import files into it.
  26 See http://wiki.openstreetmap.org/wiki/Potlatch_2/Developer_Documentation for details.
  27
  28 You'll only need OSM Rails port installed on your local machine if you are doing hard-core
  29 server-communication coding, but if generally you can use the dev server at api06.dev.openstreetmap.org
  30 for development and testing.
  31
  32
  33 === How to compile and run ===
  34
  35 Compiling Potlatch 2:
  36
  37 1) Copy the properties template file
  38   cp build.properties.template build.properties
  39
  40 2) Edit the FLEX_HOME variable in build.properties
  41  eg, FLEX_HOME=c:/flex_sdk/3.5.0.12683
  42
  43 3) ant
  44
  45 The following command will compile potlatch2 in debug configuration
  46 The result is put at resources/potlatch2.swf
  47
  48 * ant
  49
  50 The following command will compile potlatch2 in release configuration
  51
  52 * ant release
  53
  54 Compiling Halcyon as standalone viewer:
  55
  56 * ant halcyon
  57
  58 You can create class documentation (in resources/docs) using asdoc
  59
  60 * ant docs
  61
  62 You can create and run the unit tests (not that there are that many) using flexunit
  63
  64 * ant test
  65
  66 If you're using Mac OS X, you may need to tell ant to use more memory, by
  67 typing export ANT_OPTS=-Xmx500M beforehand (you can put this in your .profile).
  68
  69
  70 Compiling during development:
  71
  72 Compiling optimized versions from scratch takes a _long_ time. There are
  73 several ways to make it faster during development and also add useful
  74 debug stack traces and enable the commandline debugger (at the expense
  75 of a much larger swf file.. but we're developing so that doesn't matter!).
  76
  77 * fcsh
  78   - launches the Flex Compiler SHell -- stops the compiler having to
  79     bootstrap itself each time you invoke it. You don't /need/ this, but it
  80     does make things slightly faster (about a second a shot for me)
  81
  82 * mxmlc -load-config+=debug-config.xml potlatch2.mxml
  83   - compile potlatch2 in debug configuration -- build is incremental so you
  84     can run it again and mxmlc will only compile changes. Output has debug
  85     enabled along with decent stack traces.
  86     (you can substitute halcyon_viewer.as in the above to compile that)
  87
  88 * compile 1
  89   - when using fcsh recompile the first command
  90
  91 * compile 1
  92   - type it again to compile again. You'll really wish that up-arrow,enter
  93     worked, but Adobe is laughing at you RIGHT NOW.
  94
  95 * rlwrap
  96   - if you have it on your system (e.g. linux), rlwrap is a godsend. Launch
  97     fcsh with 'rlwrap path/to/fcsh' and up arrows will work, even persistantly
  98     across one fcsh session to the next.
  99
 100 Running:
 101
 102 * Flash security model sucks. If you want to use internet resource (e.g. map calls to the dev
 103   server) the binary must have been served from "teh internets". Run resources/server.rb to launch a local
 104   server, then go to http://localhost:3333/potlatch2.html to get started (or if you're already running e.g.
 105   Apache locally, feel free to use that instead.)
 106
 107   Alternatively, you can update your global Flash security settings to "always trust files" in your local dev area:
 108   http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04.html
 109   Then you can run the swf file directly.
 110
 111 * If you are doing offline development, you will need a rails_port install. You
 112   will need to add an OAuth application by going to
 113   http://rails-port.local/user/<username>/oauth_clients/new
 114   Enter the following details (assuming the above point):
 115   * Name (Required): Potlatch2 (local)
 116   * Main Application URL (Required): http://localhost:3333/resources/potlatch2.html
 117   And then update resources/potlatch2.html replacing the domains.
 118
 119 === Some other stuff you might need to know ===
 120
 121 * Flex compiler runs at about the speed of a tortoise soaked in molasses which happens also to be dead.
 122 * Running the debug player helps when coding, since it'll pop up the runtime errors. You don't see them
 123   with the normal player.
 124
 125 Richard Fairhurst
 126 richard@systemeD.net
 127
 128 Dave Stubbs
 129 osm@randomjunk.co.uk
 130