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

Last change on this file since 24243 was 24180, checked in by gravitystorm, 10 years ago

Add build target for asdocs

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