source: subversion/applications/editors/potlatch2/README.txt @ 25426

Last change on this file since 25426 was 24863, checked in by stevage, 10 years ago

ADD note about changing global flash security settings
ADD note about using Flex Builder/Flash? Builder
REWORD the "before you begin" to make it easier for skim readers who never read anything properly, like me.

File size: 5.0 KB
Line 
1== Halcyon and Potlatch 2.0 - ActionScript 3 renderer and editor ==
2
3Potlatch 2.0 is the new version of the OpenStreetMap online editor.
4
5Halcyon 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
7Both are written in ActionScript 3. Potlatch 2.0 additionally uses the Flex framework.
8
9Many 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
22and earlier have this bug: http://bugs.adobe.com/jira/browse/SDK-16705 which is a major issue for the
23tag editors.
24
25If you happen to have Adobe Flex Builder 3/Flash Builder 4, you can create a project and import files into it.
26See http://wiki.openstreetmap.org/wiki/Potlatch_2/Developer_Documentation for details.
27
28You'll only need OSM Rails port installed on your local machine if you are doing hard-core
29server-communication coding, but if generally you can use the dev server at api06.dev.openstreetmap.org
30for development and testing.
31
32
33=== How to compile and run ===
34
35Compiling Potlatch 2:
36
371) Copy the properties template file
38  cp build.properties.template build.properties
39 
402) Edit the FLEX_HOME variable in build.properties 
41 eg, FLEX_HOME=c:/flex_sdk/3.5.0.12683
42 
433) ant
44
45The following command will compile potlatch2 in debug configuration
46The result is put at resources/potlatch2.swf
47
48* ant
49
50The following command will compile potlatch2 in release configuration
51
52* ant release
53
54Compiling Halcyon as standalone viewer:
55
56* ant halcyon
57
58You can create class documentation (in resources/docs) using asdoc
59
60* ant docs
61
62You can create and run the unit tests (not that there are that many) using flexunit
63
64* ant test
65
66If you're using Mac OS X, you may need to tell ant to use more memory, by
67typing export ANT_OPTS=-Xmx500M beforehand (you can put this in your .profile).
68
69
70Compiling during development:
71
72Compiling optimized versions from scratch takes a _long_ time. There are
73several ways to make it faster during development and also add useful
74debug stack traces and enable the commandline debugger (at the expense
75of 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
100Running:
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 
125Richard Fairhurst
126richard@systemeD.net
127
128Dave Stubbs
129osm@randomjunk.co.uk
130
Note: See TracBrowser for help on using the repository browser.