Installation Instructions for OS X

This page is about installing Conkeror under Mac OS X. For instructions for other operating systems, read Installation.

<<TableOfContents: execution failed [list index out of range] (see also the log)>>

Traditionally, Conkeror uses the experimental Mozilla XULRunner as its basis. Installing Conkeror using XULRunner is described in the first part of these instructions. However, many people have reported difficulties with recent versions of XULRunner under Mac OS X. If your XULRunner only says "error" when you run it, you may prefer the alternative installation procedure described in the second part, which uses a standard Firefox installation as its basis.

Installation based on XULRunner

1. Install XULRunner

Read XULRunner for guidance in installing XULRunner.

2. Install Conkeror

You can obtain Conkeror either with git or by downloading a snapshot archive.

2.1. git

To use Conkeror from the git repository, first clone the repository, using the command:

git clone git://repo.or.cz/conkeror.git

Later on, when you want to update:

git fetch
git log HEAD..origin  #optional, shows you the changes
git merge origin

3. `conkeror-spawn-helper`

If you want to be able to edit web page text fields in an external editor, you will need to build the included program, conkeror-spawn-helper. Please read ConkerorSpawnHelper for more details.

4. Build the Mac application

Run the following commands from a terminal, replacing /path/to/conkeror with the directory of your conkeror installation.

rm -rf /Applications/conkeror.mozdev.org/conkeror.app
/Library/Frameworks/XUL.framework/xulrunner-bin --install-app /path/to/conkeror

You will now have the application file /Applications/conkeror.mozdev.org/conkeror.app which you can use to launch conkeror. Alternatively, from a command line prompt:

/Applications/conkeror.mozdev.org/conkeror.app/Contents/MacOS/xulrunner -foreground [URL]

5. Default browser and external URL opening

To enable both setting Conkeror as the default browser, and externally opening URLs in Conkeror ("remoting" in Conkeror terminology) from the command line, shell scripts, AppleScript, launchers, and so on:

First, open /Applications/conkeror.mozdev.org/conkeror.app/Contents/Info.plist in your editor of choice and add the following directly after <dict>

<key>CFBundleSignature</key>
<string>CNKR</string>
<key>CFBundleIdentifier</key>
<string>org.mozdev.conkeror</string>
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>Web site URL</string>
    <key>CFBundleURLSchemes</key>
      <array>
        <string>http</string>
        <string>https</string>
      </array>
  </dict>
  <dict>
    <key>CFBundleURLName</key>
    <string>Local file URL</string>
    <key>CFBundleURLSchemes</key>
      <array>
        <string>file</string>
      </array>
  </dict>
</array>
<key>CFBundleDevelopmentRegion</key>
<string>English</string>

Now update with the command

touch /Applications/conkeror.mozdev.org/conkeror.app

Next simply open Safari. Goto the preferences option from the 'Safari' menu. On the 'General' tab, set conkeror.app as your default browser under 'Default web browser'.

Installation based on Firefox

This alternative installation procedure exploits the fact that recent Firefox versions can run XUL applications just like XULRunner does. The advantage of this approach is that it's much easier to install Firefox than to install XULRunner, and many users have Firefox installed anyway. The procedure described here has been tested with Firefox versions 8 to 10. In the following, a standard Firefox installation under /Applications/Firefox.app is assumed to exist. You also need to have Apple's XCode package installed, because two small C programs are compiled as part of the application creation process.

1. Option 1: Manual bundle creation

1.1. Get the Conkeror source code

This works just as described in the XULRunner-based installation, see above. You can either use git or download a snapshot.

1.2. Get the script that generates the Conkeror application

Just click here.

1.3. Make your application bundle

tar xzf conkeror_on_macosx.tar.gz
cd conkeror_on_macosx
./make_app.sh /path/to/conkeror

where /path/to/conkeror points to the directory that contains the file application.ini. This generates Conkeror.app in the same directory. You can then move it wherever you wish. The Conkeror application can be used just like any other browser for Mac OS X. You can also make it your default browser. The bundle also contains conkeror_spawn_helper, so there is nothing else to do.

2. Option 2: Scripted bundle creation

Essentially, this just follows the steps listed in Option 1 to create a Conkeror.app bundle and (optionally) install it into /Applications. It uses unofficial artwork from http://www.conkeror.org/Artwork for the icon.

2.1. Clone the bundle creation repository

git clone git://github.com/smazga/conkeror_mac_bundler.git

2.2. Create and install the bundle

make install

3. Limitations

The Conkeror application bundle created by this procedure has one defect, which may or may not be serious depending on your working habits. When all Conkeror windows are closed, the application remains active (this is how Mac OS X applications work) and has a menu that you can switch to. However, that menu is the Firefox menu, not the Conkeror menu, and selecting any menu item will crash Conkeror. In practice that means that if you close all open windows, you cannot open a new one through the menu. You can, however, open a new window by opening a URL, e.g. from the terminal using the open command. If you set Conkeror to be your default browser, opening a URL from any other application will also correctly open a new Conkeror window.

Opening a URL externally in the Conkeror application

Mac OS X applications work a bit differently from Unix command line tools. If you want to open a URL in Conkeror from the command line ("remoting", in Conkeror terminology), you should use the Mac OS X open command:

open -a Conkeror http://conkeror.org/

If you have set Conkeror as your default browser, you can drop the -a Conkeror part.


My cross-platform pull-and-build shell script for Conkeror on linux and OS X can be found here: https://gist.github.com/PhilHudson/5645427

-- PhilHudson 2013-05-24 18:24:59