Fix bug in TileSet where certain tiles would never get loaded. (Turned out to be...
[potlatch2.git] / 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 You'll only need OSM Rails port installed on your local machine if you are doing hard-core 
26 server-communication coding, but if generally you can use the dev server at api06.dev.openstreetmap.org
27 for development and testing.
28
29
30 === How to compile and run ===
31
32 Compiling Potlatch 2:
33
34 Before you start, copy the properties template file, and edit the FLEX_HOME variable
35   cp build.properties.template build.properties
36
37 The following command will compile potlatch2 in debug configuration
38 The result is put at resources/potlatch2.swf
39
40 * ant
41
42 The following command will compile potlatch2 in release configuration
43
44 * ant release
45
46 Compiling Halcyon as standalone viewer:
47
48 * ant halcyon
49
50 You can create class documentation (in resources/docs) using asdoc
51
52 * ant docs
53
54 You can create and run the unit tests (not that there are that many) using flexunit
55
56 * ant test
57
58 If you're using Mac OS X, you may need to tell ant to use more memory, by
59 typing export ANT_OPTS=-Xmx500M beforehand (you can put this in your .profile).
60
61
62 Compiling during development:
63
64 Compiling optimized versions from scratch takes a _long_ time. There are
65 several ways to make it faster during development and also add useful
66 debug stack traces and enable the commandline debugger (at the expense
67 of a much larger swf file.. but we're developing so that doesn't matter!).
68
69 * fcsh
70   - launches the Flex Compiler SHell -- stops the compiler having to
71     bootstrap itself each time you invoke it. You don't /need/ this, but it
72     does make things slightly faster (about a second a shot for me)
73
74 * mxmlc -load-config+=debug-config.xml potlatch2.mxml
75   - compile potlatch2 in debug configuration -- build is incremental so you
76     can run it again and mxmlc will only compile changes. Output has debug
77     enabled along with decent stack traces.
78     (you can substitute halcyon_viewer.as in the above to compile that)
79
80 * compile 1 
81   - when using fcsh recompile the first command
82
83 * compile 1
84   - type it again to compile again. You'll really wish that up-arrow,enter 
85     worked, but Adobe is laughing at you RIGHT NOW.
86
87 * rlwrap
88   - if you have it on your system (e.g. linux), rlwrap is a godsend. Launch
89     fcsh with 'rlwrap path/to/fcsh' and up arrows will work, even persistantly
90     across one fcsh session to the next.
91
92 Running:
93
94 * Flash security model sucks. If you want to use internet resource (e.g. map calls to the dev
95   server) the binary must have been served from "teh internets". Run resources/server.rb to launch a local 
96   server, then go to http://localhost:3333/potlatch2.html to get started (or if you're already running e.g. 
97   Apache locally, feel free to use that instead.
98   
99 * If you are doing offline development, you will need a rails_port install. You 
100   will need to add an OAuth application by going to 
101   http://rails-port.local/user/<username>/oauth_clients/new
102   Enter the following details (assuming the above point):
103   * Name (Required): Potlatch2 (local)
104   * Main Application URL (Required): http://localhost:3333/resources/potlatch2.html
105   And then update resources/potlatch2.html replacing the domains.
106
107 === Some other stuff you might need to know ===
108
109 * Flex compiler runs at about the speed of a tortoise soaked in molasses which happens also to be dead.
110 * Running the debug player helps when coding, since it'll pop up the runtime errors. You don't see them
111   with the normal player.
112   
113 Richard Fairhurst
114 richard@systemeD.net
115
116 Dave Stubbs
117 osm@randomjunk.co.uk
118