git.maemo.org Git - browser-switch/blob - 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 # 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 disabled by default; set
  96 continuous_mode to 1 to enable.  [This option corresponds to the
  97 "Optimize Browser Switchboard for" option group in the UI; "Lower memory
  98 usage" corresponds to continuous_mode off, while "Faster browser startup
  99 time" corresponds to continuous_mode on.]
 100
 101 The "tear", "microb", "fennec", and "midori" options for default_browser
 102 should be self-explanatory.  [These correspond to the options in the
 103 "Default browser" combo box in the UI.]
 104
 105 If the default browser is "other", Browser Switchboard will run the
 106 program specified in other_browser_cmd as the default browser, with a
 107 URI replacing the %s on the command line; for example, if
 108 other_browser_cmd is set to "some_browser %s", and Browser Switchboard
 109 is asked to load http://www.google.com/, it will perform the equivalent
 110 of typing in
 111
 112 $ some_browser 'http://www.google.com/'
 113
 114 at a shell.  [In the UI, setting "Default brower" to "Other" activates
 115 the "Command (%s for URI)" setting, which corresponds to the value of
 116 other_browser_cmd.]
 117
 118 The logging option controls where Browser Switchboard sends its debug
 119 logging output to.  You should not need to change this unless you're
 120 debugging Browser Switchboard, and there is no UI for this option.  The
 121 default option is "stdout", which means you won't see output unless you
 122 run Browser Switchboard from the shell.  "syslog" will send the output
 123 to the system log (assuming you have a syslogd set up on your device),
 124 and "none" disables debug logging entirely.
 125
 126 On Fremantle only, autostart_microb controls whether MicroB is
 127 prestarted when the device boots.  By default, MicroB is prestarted only
 128 when MicroB is set as the default browser; you can force MicroB to
 129 always prestart by setting autostart_microb = 1, while you can force it
 130 to never prestart by setting autostart_microb = 0.  [This option has no
 131 corresponding UI at the moment.]
 132
 133
 134 Browser Switchboard and MicroB's browserd:
 135
 136 MicroB uses a background process called browserd to decrease its load
 137 time.  Browser Switchboard knows how to launch MicroB without having
 138 browserd running all the time, so if you don't plan on using MicroB
 139 often, you can disable browserd (for example, by using the
 140 maemo-control-services control panel applet available in Maemo Extras to
 141 disable tablet-browser-daemon).  This will save you about 1 MB of
 142 memory, but add a few seconds to MicroB's load time.
 143
 144
 145 Uninstalling Browser Switchboard:
 146
 147 Remove the Browser Switchboard package using the Application Manager,
 148 and everything should be back to normal.  If you experience problems
 149 after uninstalling, try restarting your device first; if that fixes
 150 things, please report this as a bug.
 151
 152
 153 Compiling Browser Switchboard:
 154
 155 If for some reason you don't want to use the prebuilt binary package to
 156 install Browser Switchboard, you can compile and install by hand:
 157 1. You will need a copy of the SDK for your device.  Make sure the
 158 following packages are installed: libdbus-glib-1-dev for
 159 browser-switchboard; libdbus-1-dev, libgtk2.0-dev, libhildon1-dev,
 160 hildon-control-panel-dev for the config UI.
 161 2. Download the source tarball: browser-switchboard_X.Y.orig.tar.gz
 162 3. Unpack the source tarball in your SDK install:
 163
 164 SDK$ tar -xvzf browser-switchboard_X.Y.orig.tar.gz
 165 SDK$ cd browser-switchboard-X.Y
 166
 167 4. Compile:
 168
 169 SDK$ make diablo
 170 SDK$ make -C config-ui diablo-plugin
 171
 172 (Replace "diablo" with "fremantle" and "diablo-plugin" with
 173 "fremantle-plugin" if compiling for Fremantle.
 174
 175 If you want the standalone config application instead of the Control
 176 Panel plugin, do
 177 SDK$ make -C config-ui diablo-hildon-app
 178 instead.
 179
 180 If you're using the Scratchbox2-based SDK+, you want
 181 SDK+$ sb2 make
 182 etc. as usual.)
 183
 184 5. Install to a temporary directory, and tar up the result:
 185
 186 SDK$ make DESTDIR=temp install
 187 SDK$ make -C config-ui install
 188 SDK$ cd temp
 189 SDK$ tar cf stuff.tar .
 190
 191 6. As root on your device, move files that will be replaced in the
 192 install process out of the way:
 193
 194 DEVICE# mv /usr/share/dbus-1/services/com.nokia.osso_browser.service
 195   /usr/share/dbus-1/services/com.nokia.osso_browser.bak
 196 DEVICE# mv /usr/bin/browser /usr/bin/browser.bak
 197
 198 7. Copy the tar file from step 5 to your device, and as root, unpack it
 199 in the root directory of your device:
 200
 201 DEVICE# cd /
 202 DEVICE# tar xf /path/to/stuff.tar
 203
 204 To uninstall, remove the files you installed, restore the backup copies,
 205 and reboot your device.
 206
 207
 208 Bug Reports and Patches:
 209
 210 Bug reports, patches, and suggested improvements can either be sent to
 211 the maintainer via email (see below) or posted in the Tear thread on the
 212 talk.maemo.org forums (http://talk.maemo.org/showthread.php?t=28539).
 213
 214
 215 Source Code Repository:
 216
 217 Source code is hosted in a Git (http://git-scm.com/) repository on
 218 git.maemo.org.  You can get a copy of the current development version by
 219 cloning the repository:
 220
 221 $ git clone http://git.maemo.org/projects/browser-switch
 222
 223 or you can browse the source using gitweb
 224 (http://git.maemo.org/projects/browser-switch/?p=browser-switch;a=summary).
 225
 226
 227 Maintainer:
 228
 229 Steven Luo <steven+maemo@steven676.net> is the primary maintainer, with
 230 Jason Simpson (the original developer) assisting in development.
 231
 232
 233 License:
 234
 235 Browser Switchboard is available under the terms of the GNU General
 236 Public License (GPL), version 2 or later (see the file LICENSE in the
 237 source).