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 === What you'll need ===
  10
  11 * Flex SDK - http://www.adobe.com/products/flex/ (free, OS X/Windows/Linux) (Use version 3 and NOT version 4 as there is a compatibility issue)
  12 * AS3 docs - http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/
  13 * Flash debug player - http://www.adobe.com/support/flashplayer/downloads.html
  14 * Basically you might as well just sell your soul to Adobe
  15
  16 You'll only need OSM Rails port installed on your local machine if you are doing hard-core
  17 server-communication coding, but if generally you can use the dev server at api06.dev.openstreetmap.org
  18 for development and testing.
  19
  20 === How to compile and run ===
  21
  22 Compiling Potlatch 2:
  23
  24 The following command will compile potlatch2 in optimized configuration
  25 The result is put at resources/potlatch2.swf
  26
  27 * mxmlc potlatch2.mxml
  28
  29
  30 Compiling Halcyon as standalone viewer:
  31
  32 * mxmlc halcyon_viewer.as
  33
  34
  35 Compiling during development:
  36
  37 Compiling optimized versions from scratch takes a _long_ time. There are
  38 several ways to make it faster during development and also add useful
  39 debug stack traces and enable the commandline debugger (at the expense
  40 of a much larger swf file.. but we're developing so that doesn't matter!).
  41
  42 * fcsh
  43   - launches the Flex Compiler SHell -- stops the compiler having to
  44     bootstrap itself each time you invoke it. You don't /need/ this, but it
  45     does make things slightly faster (about a second a shot for me)
  46
  47 * mxmlc -load-config+=debug-config.xml potlatch2.mxml
  48   - compile potlatch2 in debug configuration -- build is incremental so you
  49     can run it again and mxmlc will only compile changes. Output has debug
  50     enabled along with decent stack traces.
  51     (you can substitute halcyon_viewer.as in the above to compile that)
  52
  53 * compile 1
  54   - when using fcsh recompile the first command
  55
  56 * compile 1
  57   - type it again to compile again. You'll really wish that up-arrow,enter
  58     worked, but Adobe is going laughing at you RIGHT NOW.
  59
  60 Running:
  61
  62 * Flash security model sucks. If you want to use internet resource (e.g. map calls to the dev
  63   server) the binary must have been served from "teh internets". Run resources/server.rb to launch a local
  64   server, then go to http://localhost:3333/potlatch2.html to get started (or if you're already running e.g.
  65   Apache locally, feel free to use that instead.
  66
  67 * If you are doing offline development, you will need a rails_port install. You
  68   will need to add an OAuth application by going to
  69   http://rails-port.local/user/<username>/oauth_clients/new
  70   Enter the following details (assuming the above point):
  71   * Name (Required): Potlatch2 (local)
  72   * Main Application URL (Required): http://localhost:3333/resources/potlatch2.html
  73   And then update resources/potlatch2.html replacing the domains.
  74
  75 === Some other stuff you might need to know ===
  76
  77 * Flex compiler runs at about the speed of a tortoise soaked in molasses which happens also to be dead.
  78 * Running the debug player helps when coding, since it'll pop up the runtime errors. You don't see them
  79   with the normal player.
  80
  81 Richard Fairhurst
  82 richard@systemeD.net
  83
  84 Dave Stubbs
  85 osm@randomjunk.co.uk
  86