Commenting for ASDoc
[potlatch2.git] / README.txt
index 7f79b1e..52c3db8 100644 (file)
-== Halcyon - ActionScript 3 renderer for Potlatch 2.0 ==
+== Halcyon and Potlatch 2.0 - ActionScript 3 renderer and editor ==
 
-Here's some embryonic unfinished stuff to play with.
+Potlatch 2.0 is the new version of the OpenStreetMap online editor.
 
-This is a live OSM renderer written in AS3 which will one day grow into a beautiful map editor. It's rules-based (like, say, Mapnik) and does dotted lines, text on a path, casing, icons for POIs, all of that.
+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.
+
+Both are written in ActionScript 3. Potlatch 2.0 additionally uses the Flex framework.
+
+Many icons used in halcyon/potlatch2 are based on the awesome CC0-licensed SJJB icons project. http://www.sjjb.co.uk/mapicons/
 
 === What you'll need ===
 
-* OSM Rails port installed on your local machine
-* Flex SDK - http://www.adobe.com/products/flex/ (free, OS X/Windows/Linux)
+* Flex SDK 3.4 or 3.5 
+** Product page: http://www.adobe.com/products/flex/ 
+** Flex 3 Download page: http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+3 (free, OS X/Windows/Linux)
 * AS3 docs - http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/
 * Flash debug player - http://www.adobe.com/support/flashplayer/downloads.html
 * Basically you might as well just sell your soul to Adobe
+* Ant
+
+***Do not use FlexSDK <= 3.3 or > 4***. There are compatibility errors with version 4, and 3.3
+and earlier have this bug: http://bugs.adobe.com/jira/browse/SDK-16705 which is a major issue for the
+tag editors.
+
+You'll only need OSM Rails port installed on your local machine if you are doing hard-core 
+server-communication coding, but if generally you can use the dev server at api06.dev.openstreetmap.org
+for development and testing.
+
 
 === How to compile and run ===
 
-Compiling:
+Compiling Potlatch 2:
+
+Before you start, copy the properties template file, and edit the FLEX_HOME variable
+  cp build.properties.template build.properties
+
+The following command will compile potlatch2 in debug configuration
+The result is put at resources/potlatch2.swf
+
+* ant
+
+The following command will compile potlatch2 in release configuration
+
+* ant release
+
+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
+
+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).
+
+
+Compiling during development:
+
+Compiling optimized versions from scratch takes a _long_ time. There are
+several ways to make it faster during development and also add useful
+debug stack traces and enable the commandline debugger (at the expense
+of a much larger swf file.. but we're developing so that doesn't matter!).
+
 * fcsh
-  - launches the Flex Compiler SHell
-* mxmlc -target-player=10.0.0 -managers=flash.fonts.AFEFontManager -output=/path/to/halcyon.swf /path/to/halcyon.mxml 
-  - compile for the first time
+  - launches the Flex Compiler SHell -- stops the compiler having to
+    bootstrap itself each time you invoke it. You don't /need/ this, but it
+    does make things slightly faster (about a second a shot for me)
+
+* mxmlc -load-config+=debug-config.xml potlatch2.mxml
+  - compile potlatch2 in debug configuration -- build is incremental so you
+    can run it again and mxmlc will only compile changes. Output has debug
+    enabled along with decent stack traces.
+    (you can substitute halcyon_viewer.as in the above to compile that)
+
 * compile 1 
-  - compile each subsequent time (_much_ faster than using mxmlc every time)
+  - when using fcsh recompile the first command
+
+* compile 1
+  - type it again to compile again. You'll really wish that up-arrow,enter 
+    worked, but Adobe is laughing at you RIGHT NOW.
 
-* for nice debug reports compile with the mxmlc command:
-  mxmlc -managers=flash.fonts.AFEFontManager -compiler.debug -compiler.verbose-stacktraces -output=halcyon.swf halcyon.mxml
+* rlwrap
+  - if you have it on your system (e.g. linux), rlwrap is a godsend. Launch
+    fcsh with 'rlwrap path/to/fcsh' and up arrows will work, even persistantly
+    across one fcsh session to the next.
 
 Running:
-* Make sure test.yaml and icons/ are in the same directory as halcyon.swf
-* Open halcyon.swf in your browser
+
+* Flash security model sucks. If you want to use internet resource (e.g. map calls to the dev
+  server) the binary must have been served from "teh internets". Run resources/server.rb 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.
+  
+* If you are doing offline development, you will need a rails_port install. You 
+  will need to add an OAuth application by going to 
+  http://rails-port.local/user/<username>/oauth_clients/new
+  Enter the following details (assuming the above point):
+  * Name (Required): Potlatch2 (local)
+  * Main Application URL (Required): http://localhost:3333/resources/potlatch2.html
+  And then update resources/potlatch2.html replacing the domains.
 
 === Some other stuff you might need to know ===
 
-* The as3yaml library has been patched a bit to actually make it work. It will nonetheless spit out 300 warnings on Flex SDK 3.3.
-* The stuff about -managers=flash.fonts.AFEFontManager is probably only required on OS X.
 * Flex compiler runs at about the speed of a tortoise soaked in molasses which happens also to be dead.
-
-
+* Running the debug player helps when coding, since it'll pop up the runtime errors. You don't see them
+  with the normal player.
+  
 Richard Fairhurst
 richard@systemeD.net
+
+Dave Stubbs
+osm@randomjunk.co.uk
+