Fremantle: Make DBusGProxy static in launch_microb_open_window()
[browser-switch] / README
1 BROWSER SWITCHBOARD
2 version 3.3
3
4 Browser Switchboard is a program which allows you to choose which
5 browser to use as the default browser. It supports MicroB, Tear,
6 Mobile Firefox, Opera Mobile, and Midori out of the box, and can also be
7 used to launch MicroB without having browserd running.  A Control Panel
8 applet to choose the default browser is provided.
9
10
11 Download:
12 Binary packages and source are available for download from the project
13 page on garage.maemo.org: https://garage.maemo.org/frs/?group_id=1159
14
15
16 Quick Start:
17 1. Download the binary package: browser-switchboard_X.Y-Z_all.deb
18 (where X.Y-Z is the version number, of course).
19 2. Install the package using the Application Manager (open the
20 Application Manager, then select Application->Install from file in the
21 menu).
22
23 You can now select the default browser by using the Browser Switchboard
24 applet in the Control Panel.  Links in most applications, locally-saved
25 web pages opened from the file manager, and (for Maemo 4.x) entries in
26 the Web sidebar panel will open in the browser that you select as the
27 default.  Opening the "Web" menu entry and running "browser" from the
28 shell will also cause your chosen default browser to open.  If you don't
29 configure a default browser, MicroB will continue to be used as the
30 default browser.
31
32 No matter which browser you select as the default, MicroB can always be
33 opened via the MicroB menu entry in the applications menu (for Maemo
34 4.x, installed in the Extras menu by default), or by running "microb"
35 from the shell.  While MicroB is open, it will receive all links from
36 other applications; closing MicroB will restore your chosen default
37 browser.
38
39 If you experience trouble after installing the package, try rebooting
40 your device.  If that fixes things, please report this as a bug.
41
42
43 Configuring the Default Browser by Hand:
44
45 If for some reason, you don't want to use the Control Panel applet to
46 configure Browser Switchboard, you can create the configuration file by
47 hand from a shell.  Run the following (where $ is your prompt, not
48 something you type):
49
50 $ cat > $HOME/.config/browser-switchboard <<EOF
51 default_browser = "your_browser"
52 EOF
53
54 where your_browser can be one of "tear", "microb", "fennec", "opera",
55 "midori" or "other" (see below for more on the "other" option).  You can
56 of course also edit the $HOME/.config/browser-switchboard file with your
57 favorite text editor.
58
59 To restore the default behavior, just delete the config file:
60
61 $ rm $HOME/.config/browser-switchboard
62
63
64 Advanced Configuration:
65
66 Here's a more complete sample configuration file:
67
68 # BEGIN SAMPLE CONFIG FILE
69 # This is a comment
70 # continuous_mode: 0 -- close after handling a request; 1 -- run
71 # continuously in the background (default)
72 # On Fremantle, this is forced to 1 regardless of config setting
73 continuous_mode = 1
74 # default_browser: "tear", "microb", "fennec", "midori", "opera" or
75 # "other"
76 default_browser = "tear"
77 # other_browser_cmd: If default browser is "other", what program
78 # to run (%s will be replaced by URI)
79 #other_browser_cmd = "some_browser %s"
80 # logging: Where log output should go: "stdout", "syslog", "none"
81 #logging = "stdout"
82 # autostart_microb: Fremantle only: whether MicroB should be
83 # prestarted in the background: 0 -- never prestart MicroB; 1 -- always
84 # prestart MicroB; -1 -- only prestart MicroB when MicroB is the default
85 # browser (default behavior if unset)
86 #autostart_microb = 0
87 # END SAMPLE CONFIG FILE
88
89 Lines beginning with # characters are comments and are ignored by the
90 script.  [Most options correspond directly to an option or option group
91 in the configuration UI.]
92
93 In continuous mode, Browser Switchboard keeps running in the background
94 instead of closing after handling each request.  This saves a bit of
95 startup time for each link (on my N800 running Diablo), but costs you
96 about 150 KB extra memory.  Continuous mode is enabled by default; set
97 continuous_mode to 0 to enable.  On Fremantle, continuous mode is always
98 enabled regardless of the value of this config setting, to provide
99 better compatibility with MicroB's behavior.  [This option corresponds
100 to the "Optimize Browser Switchboard for" option group in the UI; "Lower
101 memory usage" corresponds to continuous_mode off, while "Faster browser
102 startup time" corresponds to continuous_mode on.]
103
104 The "tear", "microb", "fennec", "opera" and "midori" options for
105 default_browser should be self-explanatory.  [These correspond to the
106 options in the "Default browser" combo box in the UI.]
107
108 If the default browser is "other", Browser Switchboard will run the
109 program specified in other_browser_cmd as the default browser, with a
110 URI replacing the %s on the command line; for example, if
111 other_browser_cmd is set to "some_browser %s", and Browser Switchboard
112 is asked to load http://www.google.com/, it will perform the equivalent
113 of typing in 
114
115 $ some_browser 'http://www.google.com/'
116
117 at a shell.  [In the UI, setting "Default brower" to "Other" activates
118 the "Command (%s for URI)" setting, which corresponds to the value of
119 other_browser_cmd.]
120
121 The logging option controls where Browser Switchboard sends its debug
122 logging output to.  You should not need to change this unless you're
123 debugging Browser Switchboard, and there is no UI for this option.  The
124 default option is "stdout", which means you won't see output unless you
125 run Browser Switchboard from the shell.  "syslog" will send the output
126 to the system log (assuming you have a syslogd set up on your device),
127 and "none" disables debug logging entirely.
128
129 On Fremantle only, autostart_microb controls whether MicroB is
130 prestarted when the device boots and whether the MicroB browser process
131 is left running when no browser windows are open.  By default, MicroB is
132 prestarted (and the process left open when no browser windows are open)
133 only when MicroB is set as the default browser; you can force MicroB to
134 always prestart by setting autostart_microb = 1, while you can force it
135 to never prestart by setting autostart_microb = 0.  [This option has no
136 corresponding UI at the moment.]
137
138
139 The browser-switchboard-config Command-Line Configuration Tool:
140
141 A command-line configuration utility is provided to allow programs and
142 scripts to query and set Browser Switchboard configuration variables.
143 For example,
144
145 $ browser-switchboard-config -b
146
147 will display the default browser, and 
148
149 $ browser-switchboard-config -s -b "opera"
150
151 will set the default browser to Opera Mobile.  See the help output from
152 running browser-switchboard-config with no arguments for more
153 information.
154
155 The primary purpose of this tool is to allow browser vendors to provide
156 an option in their browsers to set themselves as the default browser,
157 via something like this (shell-like pseudocode):
158
159 if [ -x /usr/bin/browser-switchboard-config ]; then
160         if [ `browser-switchboard-config -b` = "mybrowser" ]; then
161                 display "MyBrowser is the default browser."
162         else
163                 button "Make MyBrowser the default browser"
164                 action "browser-switchboard-config -s -b mybrowser"
165         fi
166 else
167         display "Install Browser Switchboard to make MyBrowser the default browser"
168 fi
169
170 Browser vendors: setting yourself as the default browser without
171 prompting the user first (via package maintainer scripts, for example)
172 is strongly discouraged.
173
174
175 Browser Switchboard and MicroB's browserd:
176
177 MicroB uses a background process called browserd to decrease its load
178 time.  Browser Switchboard knows how to launch MicroB without having
179 browserd running all the time, so if you don't plan on using MicroB
180 often, you can disable browserd (for example, by using the
181 maemo-control-services control panel applet available in Maemo Extras to
182 disable tablet-browser-daemon).  This will save you about 1 MB of
183 memory, but add a few seconds to MicroB's load time.
184
185
186 Uninstalling Browser Switchboard:
187
188 Remove the Browser Switchboard package using the Application Manager,
189 and everything should be back to normal.  If you experience problems
190 after uninstalling, try restarting your device first; if that fixes
191 things, please report this as a bug.
192
193
194 Compiling Browser Switchboard:
195
196 If for some reason you don't want to use the prebuilt binary package to
197 install Browser Switchboard, you can compile and install by hand:
198 1. You will need a copy of the SDK for your device.  Make sure the
199 following packages are installed: libdbus-glib-1-dev for
200 browser-switchboard; libdbus-1-dev, libgtk2.0-dev, libhildon1-dev,
201 hildon-control-panel-dev for the config UI.
202 2. Download the source tarball: browser-switchboard_X.Y.orig.tar.gz
203 3. Unpack the source tarball in your SDK install:
204
205 SDK$ tar -xvzf browser-switchboard_X.Y.orig.tar.gz
206 SDK$ cd browser-switchboard-X.Y
207
208 4. Compile:
209
210 SDK$ make diablo
211 SDK$ make -C config-ui diablo-plugin util
212
213 (Replace "diablo" with "fremantle", "diablo-plugin" with
214 "fremantle-plugin" and "util" with "fremantle-util" if compiling for
215 Fremantle.
216
217 If you want the standalone config application instead of the Control
218 Panel plugin, do 
219 SDK$ make -C config-ui diablo-hildon-app
220 instead.
221
222 If you're using the Scratchbox2-based SDK+, you want
223 SDK+$ sb2 make
224 etc. as usual.)
225
226 5. Install to a temporary directory, and tar up the result:
227
228 SDK$ make DESTDIR=temp install
229 SDK$ make DESTDIR=temp -C config-ui install
230 SDK$ cd temp
231 SDK$ tar cf stuff.tar .
232
233 (On Fremantle, add a
234 SDK$ make DESTDIR=temp install-xsession-script
235 before creating the tarball.)
236
237 6. As root on your device, move files that will be replaced in the
238 install process out of the way:
239
240 DEVICE# mv /usr/share/dbus-1/services/com.nokia.osso_browser.service
241   /usr/share/dbus-1/services/com.nokia.osso_browser.bak
242 DEVICE# mv /usr/bin/browser /usr/bin/browser.bak
243
244 7. Copy the tar file from step 5 to your device, and as root, unpack it
245 in the root directory of your device:
246
247 DEVICE# cd /
248 DEVICE# tar xf /path/to/stuff.tar
249
250 To uninstall, remove the files you installed, restore the backup copies,
251 and reboot your device.
252
253
254 Bug Reports and Patches:
255
256 Bug reports, patches, and suggested improvements can either be sent to
257 the maintainer via email (see below) or posted in the Tear thread on the
258 talk.maemo.org forums (http://talk.maemo.org/showthread.php?t=28539).
259
260
261 Source Code Repository:
262
263 Source code is hosted in a Git (http://git-scm.com/) repository on
264 git.maemo.org.  You can get a copy of the current development version by
265 cloning the repository:
266
267 $ git clone http://git.maemo.org/projects/browser-switch
268
269 or you can browse the source using gitweb
270 (http://git.maemo.org/projects/browser-switch/?p=browser-switch;a=summary).
271
272
273 Maintainer:
274
275 Steven Luo <steven+maemo@steven676.net> is the primary maintainer, with
276 Jason Simpson (the original developer) assisting in development.
277
278
279 License:
280
281 Browser Switchboard is available under the terms of the GNU General
282 Public License (GPL), version 2 or later (see the file LICENSE in the
283 source).