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