source: xsoft/graphweb/firefox.xml@ a41f643

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY firefox-download-http "http://releases.mozilla.org/pub/mozilla.org/firefox/releases/&firefox-version;/source/firefox-&firefox-version;.source.tar.bz2">
  <!ENTITY firefox-download-ftp  "ftp://ftp.mozilla.org/pub/mozilla.org/firefox/releases/&firefox-version;/source/firefox-&firefox-version;.source.tar.bz2">
  <!ENTITY firefox-md5sum        "458051557ff49e6a352c1d56eee5782a">
  <!ENTITY firefox-size          "47 MB">
  <!ENTITY firefox-buildsize     "321 MB (stand-alone) or 303 MB (on xulrunner)">
  <!ENTITY firefox-time          "12 SBU (stand-alone) or 0.1 SBU (on xulrunner)">
]>

<sect1 id="firefox" xreflabel="Firefox-&firefox-version;">
  <?dbhtml filename="firefox.html" ?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Firefox-&firefox-version;</title>

  <indexterm zone="firefox">
    <primary sortas="a-Firefox">Firefox</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Firefox</title>

    <para><application>Firefox</application> is a stand-alone browser
    based on the <application>Mozilla</application> codebase.</para>

    <para>With the introduction of firefox-3.x, the
    <application>pkgconfig</application> files for the Gecko engine (and for
    <application>nss</application> and <application>nspr</application>) are not
    installed.  This means that applications such as
    <application>Epiphany</application> can no longer be built against firefox,
    and must instead be built against xulrunner (which is actually the same
    code, but built in a different way).  If you wish to build other packages
    which use Gecko (for the moment, probably only gnome-2.24 or later versions
    will recognize xulrunner), build <xref linkend="xulrunner"/> first.</para>

   <tip>
    <para>Firefox is updated frequently as new vulnerabilities are found.
    Consult
    <ulink url="http://www.mozilla.org/security/known-vulnerabilities/">mozilla security</ulink>
    for details of what is fixed in newer releases.  The editors cannot guess
    what will differ in newer versions: it should be straightforward to upgrade
    within the same series (3.5), but it is always possible that newer versions
    will have increased dependencies, or that something using the nss or gecko
    libraries will break.  If you update, begin by updating
    <application>xulrunner</application> if you use that, then update firefox
   (ensuring the libxul-sdk option points to the new version).</para>
   </tip>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&firefox-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&firefox-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &firefox-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &firefox-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &firefox-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &firefox-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Optional patch: <ulink
        url="&patch-root;/firefox-&firefox-version;-provide_system_nspr_nss-1.patch"/>
        (Required if using the included NSPR and NSS libs as system versions for
        other packages)</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Firefox Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended"><xref linkend="xulrunner"/> which shares all these
    dependencies, or for a standalone firefox the following Required and
    Optional dependencies:</para>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="alsa-lib"/>,
    <xref linkend="gtk2"/>,
    <xref linkend="libidl"/>
    <xref linkend="pango"/>
    <xref linkend="python"/>, and
    <xref linkend="zip"/></para>

    <para>Note: <application>libjpeg</application> should have been installed
    before <application>GTK+</application> and should exist on your system. If
    for some reason you haven't installed <application>libjpeg</application>,
    you should remove the <option>--with-system-jpeg</option> option from the
    <filename>.mozconfig</filename> file created below.</para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="dbus-glib"/>,
    <xref linkend="doxygen"/>,
    <xref linkend="curl"/> (only for crash-reporter),
    <xref linkend="gnome-vfs"/> and <xref linkend="libgnomeui"/>
    (for gnome integration),
    <xref linkend="lcms"/>,
    <xref linkend="libpng"/> (patched for apng support),
    <xref linkend="nspr"/>,
    <xref linkend="nss"/>,
    <xref linkend="startup-notification"/>.
    <xref linkend="sqlite"/>,
    <xref linkend="unzip"/>,
    <ulink url="http://www.valgrind.org/">Valgrind</ulink> (only for testing the
    jemalloc code), and
    <xref linkend="wget"/></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/firefox"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Firefox</title>

    <para>The configuration of <application>Firefox</application> is
    accomplished by creating a <filename>.mozconfig</filename> file containing
    the desired configuration options. A default <filename>.mozconfig</filename>
    is created below. To see the entire list of available configuration options
    (and an abbreviated description of each one), issue
    <command>./configure --help</command>. If you are not building against
    <application>Xulrunner</application> you must comment the 'xulrunner' items.
    You may also wish to review the entire file and uncomment any other desired
    options. If you would prefer to download the file instead of creating it by
    typing or cut-and-pasting, you can find it at <ulink
    url="&files-anduin;/firefox-&firefox-version;-mozconfig"/>
    (the file must be installed in the root of the source tree
    <filename class='directory'>mozilla</filename> directory, and named
    <filename>.mozconfig</filename>). Create the file by issuing the following
    command:</para>

<screen><?dbfo keep-together="auto"?><userinput>cat &gt; .mozconfig &lt;&lt; "EOF"
<literal># This file contains the options used in the Firefox build. You may
# need to specify additional options for your specific build needs.
# Use the information provided by running './configure --help' to
# help you determine if you need to add any additional options.
# Some additional options can be added by uncommenting the examples
# in this file or adding options by inserting a line containing
# 'ac_add_options --some-option-you-need'.  Be aware that some accepted
# options, such as '--with-system-bz2', do not affect the build.

# specify that we want to build firefox
ac_add_options --enable-application=browser

# Use the default settings specified in the source tree
. $topsrcdir/browser/config/mozconfig

# Create an object directory and specify to build the package in that
# directory. If desired, modify the location of the object directory
# to a directory inside the source tree by removing '../' from the
# line below.
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../firefox-build

# Specify the installation prefix. If you would prefer Xulrunner
# installed in a different prefix, modify the line below to fit
# your needs (the config will always be written to /etc/gre.d)
ac_add_options --prefix=/usr

# apply a minimal level of optimization (-O)
ac_add_options --enable-optimize

# These options are used so that the Xulrunner binaries are linked to
# the system-installed copies of the specified libraries instead of
# the source tree code which may not be the most recent versions.
# With the exception of libsqlite3, the libraries are statically linked.

# (Options to use system installed libraries)
# Using the shipped version of libsqlite3 has been reported to cause
# problems with other applications which were using sqlite3.
# Only comment this line if you know exactly what you are doing!
ac_add_options --enable-system-sqlite

# Comment this only if you want to use whatever patched version of cairo
# is in the shipped mozilla tree, together with the system headers.
ac_add_options --enable-system-cairo

# Comment this if you have not installed lcms.
ac_add_options --enable-system-lcms

# Comment this if you did not build libjpeg before GTK+-2.
ac_add_options --with-system-jpeg

# These two options enable support for building Xulrunner with
# system-installed versions of the Network Security Services (NSS)
# and Netscape Portable Runtime (NSPR) libraries. Comment them if
# you wish to use the included copies (not recommended).
ac_add_options --with-system-nspr
ac_add_options --with-system-nss

# Comment this if you have not built png with the apng patch.
ac_add_options --with-system-png

# The pthreads option is only used when building nspr
# Uncomment this if you build the included nspr.
#ac_add_options --with-pthreads

# zlib is included in LFS. Do not comment this line.
ac_add_options --with-system-zlib

# (Options to disable parts of the package)
# This option is used to disable the a11y support in the Xulrunner
# binaries. Comment out this option if you require a11y support.
ac_add_options --disable-accessibility

# Uncomment this if you did not build curl.
#ac_add_options --disable-crashreporter

# Comment this if you have built dbus-glib.
ac_add_options --disable-dbus

# Comment this if you have gnome-vfs and libgnomeui, and wish to
# integrate firefox into your gnome desktop
ac_add_options --disable-gnomevfs

# Comment this if you have wireless-tools installed and wish to use the new
# Necko WiFi scanning.
ac_add_options --disable-necko-wifi

# This option is added so that the Mozilla Installer program is not
# built or installed. The program is not required for a BLFS
# installation of Xulrunner.
ac_add_options --disable-installer

# If you enable javaxpcom, you must have a java compiler installed.
ac_add_options --disable-javaxpcom

# This option is added so that test libraries and programs are not
# built. These would only be required for debugging purposes.
ac_add_options --disable-tests

# Disable the updater, which is not appropriate if you build from source
ac_add_options --disable-updater

# (options to add extra parts of the package)
# This option causes the installed binaries to have the official
# Firefox name embedded in them. Due to license restrictions, you
# may not distribute binaries created using this option.  It also
# means you get a popup EULA when you first run firefox.
ac_add_options --enable-official-branding

# Use the anti-phishing measures (a blacklist of sites).
ac_add_options --enable-safe-browsing

# This option is used so that the debugging symbols are removed from
# the installed binaries during the installation process. Comment out
# this option if you may have a need to retain the debugging symbols
# in the installed binaries (the resulting binaries will be about 7MB
# bigger).
ac_add_options --enable-strip

# Uncomment this option if you desire support for dual-monitor
# display using the X-Window Xinerama libraries.
#ac_add_options --enable-xinerama

# This option identifies the default binary directory of the Xulrunner
# installation and is used to locate Xulrunner's installed files. This
# option is is only used for development purposes.
#ac_add_options --with-default-mozilla-five-home=/usr/lib/firefox-&firefox-version;

# Point to the xulrunner libraries - comment these for a standalone browser
ac_add_options --with-system-libxul
ac_add_options --with-libxul-sdk=/usr/lib/xulrunner-devel-&xulrunner-version;</literal>
EOF</userinput></screen>

    <para>If you did not install <xref linkend="xulrunner"/> or
    <xref linkend="nspr"/> and <xref linkend="nss"/>, then fix a couple of build
    errors with the following commands:</para>

<screen><userinput>patch -Np1 -i ../firefox-&firefox-version;-provide_system_nss_nspr-1.patch &amp;&amp;
sed 's@stable@unstable@' -i xulrunner/installer/mozilla-js.pc.in </userinput></screen>

    <para>Compile <application>Firefox</application> by issuing the
    following commands:</para>

<screen><userinput>make -f client.mk build</userinput></screen>

    <para>This package does not come with a test suite.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user,
    install the package:</para>

<screen role="root"><userinput>make -f client.mk install</userinput></screen>

    <para>If you are building firefox on xulrunner, as the
    <systemitem class="username">root</systemitem> user enter the following
    symbolic link:</para>

<screen role="root"><userinput>ln -sv /usr/lib/xulrunner-&xulrunner-version;/plugins \
    /usr/lib/firefox-&firefox-version;/plugins</userinput></screen>

    <para>If you've elected to use the included NSPR and NSS, while still the
    <systemitem class="username">root</systemitem> user, complete the
    installation with the following commands:</para>

<screen role="root"><userinput>for DL in \
    libnss3.so libnssutil3.so libsmime3.so libssl3.so libsoftokn3.so \
    libplds4.so libplc4.so libnspr4.so
do
    ln -sv xulrunner-&xulrunner-version;/$DL /usr/lib/$DL
done</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>make -f client.mk ...</command>: Mozilla products are
    packaged to allow the use of a configuration file which can be used to
    pass the configuration settings to the <command>configure</command>
    command. <command>make</command> uses the <filename>client.mk</filename>
    file to get initial configuration and setup parameters, then depending on
    the target parameter (<parameter>build</parameter> or
    <parameter>install</parameter>), either runs the
    <command>configure</command> script and compiles the package or installs
    the package.</para>

    <para><command>ln -sv /usr/lib/xulrunner-&xulrunner-version;/plugins
    /usr/lib/firefox-&firefox-version;/plugins</command>:
    <application>Firefox</application> looks for plugins in its own directory,
    but when building on <application>xulrunner</application> the plugins were
    installed by that package.</para>

   <tip>
    <para>If you upgrade firefox, ensure that any additional plugins are moved
    to the plugin directory of the new version.</para>
   </tip>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Firefox</title>

    <para>No specific configuration is required as long as the
    <command>firefox</command> script is in the user's path. If
    <application>Firefox</application> is installed in a non-standard location,
    then make a symlink to the <command>firefox</command> script in the
    <filename class="directory">/usr/bin</filename> directory.</para>

    <para>If your Window or Desktop Manager does not allow you to configure
    a default mail client, you can add a configuration parameter to
    <application>Firefox</application> so that an email client will start
    when you click on a <systemitem role='url'>mailto:</systemitem> URL.
    There are two parameters you need to check. The procedure to check or
    modify any of the configuration parameters is quite simple and the
    instructions here can be used to view or modify any of the
    parameters.</para>

    <para>First, open the configuration dialog by entering
    <systemitem role='url'>about:config</systemitem> in the address bar. This
    will display a list of the configuration preferences and information
    related to each one. You can use the <quote>Filter:</quote> bar to enter
    search criteria and narrow down the listed items. Changing a preference
    can be done using two methods. One, if the preference has a boolean value
    (True/False), simply double-click on the preference to toggle the value
    and two, for other preferences simply right-click on the desired line,
    choose <quote>Modify</quote> from the menu and change the value. Creating
    new preference items is accomplished in the same way, except choose
    <quote>New</quote> from the menu and provide the desired data into the
    fields when prompted.</para>

    <para>The two configuration preference items you need to check so that
    <application>Firefox</application> uses a specified default mail client
    are the <parameter>network.protocol-handler.external.mailto</parameter>
    which should be set to <option>True</option> and the
    <parameter>network.protocol-handler.app.mailto</parameter> which should
    be set to the path of the desired mail client, e.g.,
    <option>/usr/bin/thunderbird</option>.</para>

    <tip>
      <para>There is a multitude of configuration parameters you can tweak to
      customize <application>Firefox</application>. A very extensive and
      up-to-date list of these parameters can be found at <ulink
      url="http://preferential.mozdev.org/preferences.html"/>.</para>
    </tip>

    <para>Many applications look for <command>netscape</command> when they
    need to open a browser. You may wish to make the following symlink for
    convenience (as the <systemitem class="username">root</systemitem>
    user).</para>

<screen role="root"><userinput>ln -v -sf firefox /usr/bin/netscape</userinput></screen>

    <para>For installing various <application>Firefox</application> plugins,
    refer to <ulink url="http://plugindoc.mozdev.org/linux.html">Mozdev's
    PluginDoc Project</ulink>. If you have the <xref linkend="jdk"/> already
    installed, create the following link as the
    <systemitem class="username">root</systemitem> user to utilize the installed
    <application>Java</application> plugin: </para>

<screen role="root"><userinput>ln -v -s $JAVA_HOME/jre/plugin/i386/ns7/libjavaplugin_oji.so \
    /usr/lib/firefox-&firefox-version;/plugins</userinput></screen>

    <para>Some packages install Mozilla plugins into the default system-wide
    directory <filename class='directory'>/usr/lib/mozilla/plugins</filename>.
    If you have not already done this for <application>Xulrunner</application>
    create symbolic links in the <application>Firefox</application>
    plugin directory
    <filename class='directory'>/usr/lib/firefox-&firefox-version;/plugins</filename>
    to the files in the default plugin directory (you should link to the actual
    files and not other links). Alternatively, you can move or copy the files
    in the default plugin directory to the
    <application>Firefox</application> plugin directory. An example of creating
    a symbolic link is shown below. Create the links as the
    <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>ln -v -s ../../mozilla/plugins/<replaceable>&lt;plugin.so&gt;</replaceable> \
    /usr/lib/firefox-&firefox-version;/plugins</userinput></screen>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>firefox and firefox-config</seg>
        <seg>Numerous libraries, browser components, plugins, extensions, and
        helper modules installed in <filename
        class='directory'>/usr/lib/firefox-&firefox-version;</filename></seg>
        <seg>/usr/include/firefox-&firefox-version;,
        /usr/lib/firefox-&firefox-version;, and
        /usr/share/idl/firefox-&firefox-version;</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="firefox-prog">
        <term><command>firefox</command></term>
        <listitem>
          <para>is a shell script that sets up the environment and
          calls the <filename>firefox-bin</filename> binary.</para>
          <indexterm zone="firefox firefox-prog">
            <primary sortas="b-firefox">firefox</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="firefox-config">
        <term><command>firefox-config</command></term>
        <listitem>
          <para>determines the compile and linker flags that should be
          used to compile and link programs that use
          <application>Firefox</application> libraries and browser
          components.</para>
          <indexterm zone="firefox firefox-config">
            <primary sortas="b-firefox-config">firefox-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>