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