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