Customization with the .userconfig file

  • Revision slug: Mozilla/Firefox_OS/Customization_with_the_.userconfig_file
  • Revision title: Customization with the .userconfig file
  • Revision id: 390609
  • Created:
  • Creator: bkelly
  • Is current revision? No
  • Comment

Revision Content

You can customize certain aspects of the build process by putting some bash code into your .userconfig file. The .userconfig file isn't checked into source code control, so your changes won't be overwritten when you update your source tree. It needs to be created in the root of your B2G tree; that is, in the same directory as flash.sh, build.sh, and so forth.

The .userconfig file, if it exists, is sourced by the load-config.sh script, which is in turn sourced by these scripts: flash.sh, build.sh (through setup.sh), run-gdb.sh, and run-emulator.sh. The run-X.sh scripts use it to determine where Gecko is for your build.

Important: Your .userconfig file should be in your B2G source directory, not your home directory!

Changing the Gecko source tree

By default, the build uses the gecko tree, which is cloned from a tree in github. Some people like to use mozilla-inbound, or mozilla-central. To do this create your clone whereever you like and add a line to your .userconfig which sets GECKO_PATH, for example:

export B2G_DIR=${B2G_DIR:-$(cd $(dirname $0); pwd)}
echo "B2G_DIR = ${B2G_DIR}"

export GECKO_PATH=${B2G_DIR}/mozilla-inbound
echo "GECKO_PATH = ${GECKO_PATH}"

Note: if building against a custom Gecko in Mac OS X, the mozilla-central directory must be in a case sensitive file system or else GECKO_PATH will be ignored. You can check whether the file system is case sensitive by running this in a Terminal window:

echo -n This file system is case->tmp; echo -n in>>TMP; echo sensitive>>tmp; cat tmp

Note: Getting B2G_DIR the way it is above allows your .userconfig to work without having hard-coded paths.

Changing Gaia settings

Sometimes, you'd like to be able to change gaia settings. For example, enabling adb in a user build. The gaia Makefile passes in --override build/custom-settings.json when calling build/settings.py, so we can write some bash which will write {"devtools.debugger.remote-enabled": true} into the custom-settings.json file. We try to avoid changing custom-settings.json if we don't need to, so we actually write into custom-settings.json.new and if the contents differ from custom-settings.json then we'll replace it.

export GAIA_PATH=${GAIA_PATH:-$(cd gaia; pwd)}
export CUSTOM_SETTINGS="${GAIA_PATH}/build/custom-settings.json"
cat > "${CUSTOM_SETTINGS}.new" <<EOF
{"devtools.debugger.remote-enabled": true}
EOF
if [ -f ${CUSTOM_SETTINGS} ] && cmp "${CUSTOM_SETTINGS}" "${CUSTOM_SETTINGS}.new" >& /dev/null; then
  rm "${CUSTOM_SETTINGS}.new"
else
  mv "${CUSTOM_SETTINGS}.new" "${CUSTOM_SETTINGS}"
fi

Another easier way is to configure a build/custom-prefs.js file in the Gaia working directory, so that means in gaia/build/custom-prefs.js if you're in the B2G directory. See Gaia Build System Primer, Customizing the preferences.

Note:  Currently the build is not smart enough to look in a different directory based on GAIA_PATH.  This is different from how GECKO_PATH behaves.  If you wish to use a separate gaia clone you can manually run make from that directory.

Create a debug build

To build a debug build, put the following line in your .userconfig file:

export B2G_DEBUG=1

Disable the optimizer

To disable the optimizer (which may create builds that are easier to debug), add the following to your .userconfig file then rebuild:

export B2G_NOOPT=1

Disable First Time User experience

If you build and reflash alot, going through the First Time User experience can be annoying. You can disable this by adding the following to your .userconfig:

export NOFTU=1

Changing the default host compiler

On some recent distributions which use GCC 4.7 as the default compiler you will need to specify an older version in order to be able to build, to do so add two lines to your .userconfig file setting the CC and CXX variables to set the alternate C and C++ compilers respectively. For example to set the GCC 4.6 compiler on Ubuntu 12.10 use:

export CC=gcc-4.6
export CXX=g++-4.6

Or if you're using a version built from sources provide the full path to the exectuables:

export CC=/opt/gcc-4.4.7/bin/gcc
export CXX=/opt/gcc-4.4.7/bin/g++

Specify a custom Gecko object tree location

Once you start changing gecko source trees and other build options, you may want to also modify where your objects get stored (so, for example, all of your debug objects go into a different tree from your non-debug objects). So you might do something like:

export GECKO_OBJDIR=${GECKO_PATH}/objdir-gonk-debug

Using ${GECKO_PATH} makes it easy to switch between different gecko trees (eg: central, beta, aurora, etc).

Keeping both debug and non-debug objects

You can use your .userconfig file to switch back and forth between debug and release builds without having to rebuild everything each time!

export B2G_DIR=${B2G_DIR:-$(cd $(dirname $0); pwd)}
echo "B2G_DIR = ${B2G_DIR}"

export GECKO_PATH=${B2G_DIR}/mozilla-inbound
echo "GECKO_PATH = ${GECKO_PATH}"

export B2G_DEBUG=1
echo "B2G_DEBUG = ${B2G_DEBUG}"

export GECKO_OBJDIR=${GECKO_PATH}/objdir-gonk
if [ "${B2G_DEBUG}" != "0" ]; then
  export GECKO_OBJDIR=${GECKO_OBJDIR}-debug
fi
if [ "${GECKO_PATH/*mozilla-inbound*/mozilla-inbound}" = "mozilla-inbound" ]; then
  export GECKO_OBJDIR=${GECKO_OBJDIR}-m-i
fi
echo "GECKO_OBJDIR = ${GECKO_OBJDIR}"

The echo commands help remind you what your current settings are. To switch between debug and release builds, simply change the value of B2G_DEBUG on line 7.

Revision Source

<p>You can customize certain aspects of the build process by putting some bash code into your <code>.userconfig</code> file. The <code>.userconfig</code> file isn't checked into source code control, so your changes won't be overwritten when you update your source tree. It needs to be created in the root of your B2G tree; that is, in the same directory as <code>flash.sh</code>, <code>build.sh</code>, and so forth.</p>
<p>The <code>.userconfig</code> file, if it exists, is sourced by the <code>load-config.sh</code> script, which is in turn sourced by these scripts: <code>flash.sh</code>, <code>build.sh</code> (through <code>setup.sh</code>), <code>run-gdb.sh</code>, and <code>run-emulator.sh</code>. The <code>run-<em>X</em>.sh</code> scripts use it to determine where Gecko is for your build.</p>
<div class="warning">
  <p><strong>Important</strong>: Your .userconfig file should be in your B2G source directory, not your home directory!</p>
</div>
<h2 id="Changing_the_Gecko_source_tree">Changing the Gecko source tree</h2>
<p>By default, the build uses the gecko tree, which is cloned from a tree in github. Some people like to use <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Source_Code/Mercurial#mozilla-inbound_%28used_for_landing_your_patches%29" title="https://developer.mozilla.org/en-US/docs/Developer_Guide/Source_Code/Mercurial#mozilla-inbound_%28used_for_landing_your_patches%29">mozilla-inbound</a>, or <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Source_Code/Mercurial#mozilla-central_%28main_development_tree%29" title="https://developer.mozilla.org/en-US/docs/Developer_Guide/Source_Code/Mercurial#mozilla-central_%28main_development_tree%29">mozilla-central</a>. To do this create your clone whereever you like and add a line to your <code>.userconfig</code> which sets <code>GECKO_PATH</code>, for example:</p>
<pre>
export B2G_DIR=${B2G_DIR:-$(cd $(dirname $0); pwd)}
echo "B2G_DIR = ${B2G_DIR}"

export GECKO_PATH=${B2G_DIR}/mozilla-inbound
echo "GECKO_PATH = ${GECKO_PATH}"
</pre>
<div class="note">
  <p><strong>Note</strong>: if building against a custom Gecko in Mac OS X, the mozilla-central directory must be in a case sensitive file system or else GECKO_PATH will be ignored. You can check whether the file system is case sensitive by running this in a Terminal window:</p>
  <pre>
echo -n This file system is case-&gt;tmp; echo -n in&gt;&gt;TMP; echo sensitive&gt;&gt;tmp; cat tmp</pre>
  <p><strong>Note</strong>: Getting B2G_DIR the way it is above allows your .userconfig to work without having hard-coded paths.</p>
</div>
<h2 id="Changing_Gaia_settings">Changing Gaia settings</h2>
<p>Sometimes, you'd like to be able to change gaia settings. For example, enabling adb in a user build. The gaia Makefile passes in --override build/custom-settings.json when calling build/settings.py, so we can write some bash which will write {"devtools.debugger.remote-enabled": true} into the custom-settings.json file. We try to avoid changing custom-settings.json if we don't need to, so we actually write into custom-settings.json.new and if the contents differ from custom-settings.json then we'll replace it.</p>
<pre>
export GAIA_PATH=${GAIA_PATH:-$(cd gaia; pwd)}
export CUSTOM_SETTINGS="${GAIA_PATH}/build/custom-settings.json"
cat &gt; "${CUSTOM_SETTINGS}.new" &lt;&lt;EOF
{"devtools.debugger.remote-enabled": true}
EOF
if [ -f ${CUSTOM_SETTINGS} ] &amp;&amp; cmp "${CUSTOM_SETTINGS}" "${CUSTOM_SETTINGS}.new" &gt;&amp; /dev/null; then
&nbsp; rm "${CUSTOM_SETTINGS}.new"
else
&nbsp; mv "${CUSTOM_SETTINGS}.new" "${CUSTOM_SETTINGS}"
fi
</pre>
<p>Another easier way is to configure a <code>build/custom-prefs.js</code> file in the Gaia working directory, so that means in <code>gaia/build/custom-prefs.js</code> if you're in the B2G directory. See <a href="/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Build_System_Primer#Customizing_the_preferences" title="/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Build_System_Primer#Customizing_the_preferences">Gaia Build System Primer, Customizing the preferences</a>.</p>
<div class="note">
  <p><strong>Note:</strong>&nbsp; Currently the build is not smart enough to look in a different directory based on GAIA_PATH.&nbsp; This is different from how GECKO_PATH behaves.&nbsp; If you wish to use a separate gaia clone you can <a href="/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Build_System_Primer" title="/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Build_System_Primer">manually run make</a> from that directory.</p>
</div>
<h2 id="Create_a_debug_build">Create a debug build</h2>
<p>To build a debug build, put the following line in your <code>.userconfig</code> file:</p>
<pre>
export B2G_DEBUG=1</pre>
<h2 id="Disable_the_optimizer">Disable the optimizer</h2>
<p>To disable the optimizer (which may create builds that are easier to debug), add the following to your <code>.userconfig</code> file then rebuild:</p>
<pre>
export B2G_NOOPT=1</pre>
<h2 id="Disable_First_Time_User_experience">Disable First Time User experience</h2>
<p>If you build and reflash alot, going through the First Time User experience can be annoying. You can disable this by adding the following to your .userconfig:</p>
<pre>
export NOFTU=1</pre>
<h2 id="Changing_the_default_host_compiler">Changing the default host compiler</h2>
<p>On some recent distributions which use GCC 4.7 as the default compiler you will need to specify an older version in order to be able to build, to do so add two lines to your <code>.userconfig</code> file setting the <code>CC</code> and <code>CXX</code> variables to set the alternate C and C++ compilers respectively. For example to set the GCC 4.6 compiler on Ubuntu 12.10 use:</p>
<pre>
export CC=gcc-4.6
export CXX=g++-4.6
</pre>
<p>Or if you're using a version built from sources provide the full path to the exectuables:</p>
<pre>
export CC=/opt/gcc-4.4.7/bin/gcc
export CXX=/opt/gcc-4.4.7/bin/g++
</pre>
<h2 id="Specify_a_custom_Gecko_object_tree_location">Specify a custom Gecko object tree location</h2>
<p>Once you start changing gecko source trees and other build options, you may want to also modify where your objects get stored (so, for example, all of your debug objects go into a different tree from your non-debug objects). So you might do something like:</p>
<pre>
export GECKO_OBJDIR=${GECKO_PATH}/objdir-gonk-debug
</pre>
<p>Using <code>${GECKO_PATH}</code> makes it easy to switch between different gecko trees (eg: central, beta, aurora, etc).</p>
<h2 id="Keeping_both_debug_and_non-debug_objects">Keeping both debug and non-debug objects</h2>
<p>You can use your <code>.userconfig</code> file to switch back and forth between debug and release builds without having to rebuild everything each time!</p>
<dl>
</dl>
<pre class="brush:bash;">
export B2G_DIR=${B2G_DIR:-$(cd $(dirname $0); pwd)}
echo "B2G_DIR = ${B2G_DIR}"

export GECKO_PATH=${B2G_DIR}/mozilla-inbound
echo "GECKO_PATH = ${GECKO_PATH}"

export B2G_DEBUG=1
echo "B2G_DEBUG = ${B2G_DEBUG}"

export GECKO_OBJDIR=${GECKO_PATH}/objdir-gonk
if [ "${B2G_DEBUG}" != "0" ]; then
&nbsp; export GECKO_OBJDIR=${GECKO_OBJDIR}-debug
fi
if [ "${GECKO_PATH/*mozilla-inbound*/mozilla-inbound}" = "mozilla-inbound" ]; then
&nbsp; export GECKO_OBJDIR=${GECKO_OBJDIR}-m-i
fi
echo "GECKO_OBJDIR = ${GECKO_OBJDIR}"</pre>
<p>The <code>echo</code> commands help remind you what your current settings are. To switch between debug and release builds, simply change the value of <code>B2G_DEBUG</code> on line 7.</p>
Revert to this revision