mozilla

Revision 514361 of Gaia build system primer

  • 리비전 슬러그: Mozilla/Firefox_OS/Platform/Gaia/Build_System_Primer
  • 리비전 제목: Build System Primer
  • 리비전 아이디: 514361
  • 제작일시:
  • 만든이: jryans
  • 현재 리비전인가요? 아니오
  • 댓글 build -> build/config

리비전 내용

Please Note: This is still a work in progress.

Most of the meaningful work for the build steps are performed by the scripts that live inside the build/subdirectory of Gaia. The files consist of JavaScript files. The JS files are executed using XPCShell (also knows as JS Shell).

The Makefile

The goals

The Makefile consists of a bunch of goals. Here are the most useful:

install-gaia

This goal will push all the apps for Gaia to your device. If you want to only push a specific app, you can use the APP flag as follows:

APP=calendar make install-gaia

This directory must exist inside one of the Gaia apps directories (e.g., apps).

reset-gaia

Same as install-gaia but starts by purging and then sets up permission defaults after installing all of the apps. The apps will be in /data/local like in the engineering builds. This will also push test and debugging applications.

Be careful: while using the APP environment variable appears to work, it will put your phone in an unusable state (which is recoverable by running this goal again without the APP variable). So don't do that.

production

Same as reset-gaia but installs the webapps inside /system/b2g instead of /data/local. This goal basically allows you to emulate user builds. This will also push the same set of apps that are installed in user builds.

Be careful: while using the APP environment variable appears to work, it will put your phone in an unusable state (which is recoverable by running this goal again without the APP variable). So don't do that.

reference-workload-empty, reference-workload-light, reference-workload-medium, reference-workload-heavy, reference-workload-x-heavy

These goals push variously sized workloads to the device, helping us with debugging and fixing the performance and scalability issues we might have. These goals accept the APP environment variable, or an APPS environment variable that should contain the app names separated by a space, e.g.,

APP=sms make reference-workload-light
APPS="sms communications/contacts" make reference-workload-heavy

Environment variables

Some environment variables let you control some aspects of the build and installation on the device:

B2G_SYSTEM_APPS=1

This environment variable lets you push an app to /system/b2g instead of /data/local. You should use that when you work with a user build. This variable is automatically set when running make production. This can be used for install-gaia or reset-gaia too.

GAIA_OPTIMIZE=1

This triggers an optimization pass on the JavaScript files. This is automatically set when running make production. This can be used for install-gaia or reset-gaia too.

PRODUCTION=1

This is basically an alias for make production (or is it the other way around ?).

DEBUG=1

This lets you generate a debug profile to use with the unit tests or to develop your Firefox OS app in Firefox. You must delete the existing profile directory before trying to generate a new one.

GAIA_DEV_PIXELS_PER_PX=1

This generates a profile suitable for running on 320x480 devices. To run on higher resolution devices, You can choose 1.5 or 2 to replace images with scale subfix(ex: @1.5x.png or @2x.png).

Build process

Here is the build process when make is executed in gaia directory:

Looking for .b2g.mk & local.mk
build system would find .b2g.mk & local.mk and load them if exists
Download xulrunner
Xulrunner is used to run xpcshell script in GAIA_DIR/build/
preference.js
Generate default preferences for Firefox OS, the values might be changed with different environment variables such as DEBUG=1
variant.js
Load customization configuration from GAIA_DISTRIBUTION_DIR/variant.json for making difference app sets, wallpapers and ringtones per carriers/region
applications-data.js
Generate default data for apps such as grid layout for homescreen and search engine for Browser.
app makefiles
Makefile in app directory would be executed if exists.
setup test-agent
setup test-agent includes two make rules "test-agent-config" & "test-agent-bootstrap-apps" which is used to setup test environment for each app.
webapp-optimize.js
minify javascript, concat localization resource files to json files and generate html file for default language if necessary.
webapp-zip.js
compress to a zip file for each app and put them into profile directory.
optimize-clean.js
clean html files for default language.
contact
copy preload contact file to profile if exists in GAIA_DISTRIBUTION_DIR
extensions
copy extensions in GAIA_DIR/tools/extensions to profile directory, setup different configuration would copy different extensions.
settings.js
generate default settings for gaia
create-default-data
copy default data to profile directory
additional-extensions.js
download certain extensions to profile directory

Customizing the preferences

If you find that you have a set of custom preferences you need to set each time you flash your device, create a file called custom-prefs.js inside the build/config directory and store them in there. This keeps them from being overwritten and out of source control.

Here are some useful preferences:

// this enables marionette which lets you run performance tests
// see https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_performance_tests
user_pref("marionette.defaultPrefs.enabled", true);

// this sets the port for remote debugging your application on the device
user_pref("devtools.debugger.remote-port", 60000);

// this enables the remote debugger
user_pref("devtools.debugger.remote-enabled", true);

// this outputs debug information about the Radio Interface Layer in logcat
user_pref("ril.debugging.enabled", true);

This file is read each time you generate a profile. The safest way to be sure that everything is generated is to delete your profile first:

rm -rf profile && make profile

Then you can safely use the install-gaia goal.

FAQ

1) The device remains black after a flash

This can sometimes happen if you flash the device while it is idle. To remedy this just restart B2G by issuing the following command from the command line:

adb shell stop b2g && adb shell start b2g

 

리비전 소스

<div class="note">
 <p>Please Note: This is still a work in progress.</p>
</div>
<p>Most of the meaningful work for the build steps are performed by the scripts that live inside the build/subdirectory of Gaia. The files consist of JavaScript files. The JS files are executed using <a href="https://developer.mozilla.org/en-US/docs/XPConnect/xpcshell" title="https://developer.mozilla.org/en-US/docs/XPConnect/xpcshell">XPCShell</a> (also knows as JS Shell).</p>
<h2 id="The_Makefile">The Makefile</h2>
<h3 id="The_goals">The goals</h3>
<p>The Makefile consists of a bunch of goals. Here are the most useful:</p>
<h4 id="install-gaia">install-gaia</h4>
<p>This goal will push all the apps for Gaia to your device. If you want to only push a specific app, you can use the <code>APP</code> flag as follows:</p>
<pre class="brush: bash">
APP=calendar make install-gaia</pre>
<p>This directory must exist inside one of the Gaia apps directories (e.g., <code>apps</code>).</p>
<h4 id="reset-gaia">reset-gaia</h4>
<p>Same as <code>install-gaia</code> but starts by purging and then sets up permission defaults after installing all of the apps. The apps will be in <code>/data/local</code> like in the engineering builds. This will also push test and debugging applications.</p>
<div class="warning">
 <p>Be careful: while using the <code>APP</code> environment variable appears to work, it will put your phone in an unusable state (which is recoverable by running this goal again without the <code>APP</code> variable). So don't do that.</p>
</div>
<h4 id="production">production</h4>
<p>Same as <code>reset-gaia </code>but installs the webapps inside <code>/system/b2g</code> instead of <code>/data/local</code>. This goal basically allows you to emulate user builds. This will also push the same set of apps that are installed in user builds.</p>
<div class="warning">
 <p>Be careful: while using the <code>APP</code> environment variable appears to work, it will put your phone in an unusable state (which is recoverable by running this goal again without the <code>APP</code> variable). So don't do that.</p>
</div>
<h4 id="reference-workload-empty.2C_reference-workload-light.2C_reference-workload-medium.2C_reference-workload-heavy.2C_reference-workload-x-heavy">reference-workload-empty, reference-workload-light, reference-workload-medium, reference-workload-heavy, reference-workload-x-heavy</h4>
<p>These goals push variously sized workloads to the device, helping us with debugging and fixing the performance and scalability issues we might have. These goals accept the <code>APP</code> environment variable, or an <code>APPS</code> environment variable that should contain the app names separated by a space, e.g.,</p>
<pre class="brush: bash">
APP=sms make reference-workload-light
APPS="sms communications/contacts" make reference-workload-heavy
</pre>
<h3 id="Environment_variables">Environment variables</h3>
<p>Some environment variables let you control some aspects of the build and installation on the device:</p>
<h4 id="B2G_SYSTEM_APPS.3D1">B2G_SYSTEM_APPS=1</h4>
<p>This environment variable lets you push an app to <code>/system/b2g</code> instead of <code>/data/local</code>. You should use that when you work with a user build. This variable is automatically set when running <code>make production</code>. This can be used for <code>install-gaia</code> or <code>reset-gaia</code> too.</p>
<h4 id="GAIA_OPTIMIZE.3D1">GAIA_OPTIMIZE=1</h4>
<p>This triggers an optimization pass on the JavaScript files. This is automatically set when running <code>make production</code>. This can be used for <code>install-gaia</code> or <code>reset-gaia</code> too.</p>
<h4 id="PRODUCTION.3D1">PRODUCTION=1</h4>
<p>This is basically an alias for <code>make production</code> (or is it the other way around ?).</p>
<h4 id="DEBUG.3D1">DEBUG=1</h4>
<p>This lets you generate a debug profile to use with the <a href="/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_unit_tests" title="/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_unit_tests">unit tests</a> or to develop your Firefox OS app in Firefox. You must delete the existing profile directory before trying to generate a new one.</p>
<h4 id="GAIA_DEV_PIXELS_PER_PX.3D1">GAIA_DEV_PIXELS_PER_PX=1</h4>
<p>This generates a profile suitable for running on 320x480 devices. To run on higher resolution devices, You can choose 1.5 or 2 to replace images with scale subfix(ex: @1.5x.png or @2x.png).</p>
<h2 id="Build_process">Build process</h2>
<p>Here is the build process when make is executed in gaia directory:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/6747/gaia-build-system.001.png" style="width: 1024px; height: 768px;" /></p>
<dl>
 <dt>
  Looking for .b2g.mk &amp; local.mk</dt>
 <dd>
  build system would find .b2g.mk &amp; local.mk and load them if exists</dd>
 <dt>
  Download xulrunner</dt>
 <dd>
  Xulrunner is used to run xpcshell script in GAIA_DIR/build/</dd>
 <dt>
  preference.js</dt>
 <dd>
  Generate default preferences for Firefox OS, the values might be changed with different environment variables such as DEBUG=1</dd>
 <dt>
  variant.js</dt>
 <dd>
  Load customization configuration from GAIA_DISTRIBUTION_DIR/variant.json for making difference app sets, wallpapers and ringtones per carriers/region</dd>
 <dt>
  applications-data.js</dt>
 <dd>
  Generate default data for apps such as grid layout for homescreen and search engine for Browser.</dd>
 <dt>
  app makefiles</dt>
 <dd>
  Makefile in app directory would be executed if exists.</dd>
 <dt>
  setup test-agent</dt>
 <dd>
  setup test-agent includes two make rules "test-agent-config" &amp; "test-agent-bootstrap-apps" which is used to setup test environment for each app.</dd>
 <dt>
  webapp-optimize.js</dt>
 <dd>
  minify javascript, concat localization resource files to json files and generate html file for default language if necessary.</dd>
 <dt>
  webapp-zip.js</dt>
 <dd>
  compress to a zip file for each app and put them into profile directory.</dd>
 <dt>
  optimize-clean.js</dt>
 <dd>
  clean html files for default language.</dd>
 <dt>
  contact</dt>
 <dd>
  copy preload contact file to profile if exists in GAIA_DISTRIBUTION_DIR</dd>
 <dt>
  extensions</dt>
 <dd>
  copy extensions in GAIA_DIR/tools/extensions to profile directory, setup different configuration would copy different extensions.</dd>
 <dt>
  settings.js</dt>
 <dd>
  generate default settings for gaia</dd>
 <dt>
  create-default-data</dt>
 <dd>
  copy default data to profile directory</dd>
 <dt>
  additional-extensions.js</dt>
 <dd>
  download certain extensions to profile directory</dd>
</dl>
<h2 id="Customizing_the_preferences">Customizing the preferences</h2>
<p>If you find that you have a set of custom preferences you need to set each time you flash your device, create a file called <code>custom-prefs.js</code> inside the <code>build/config</code> directory and store them in there. This keeps them from being overwritten and out of source control.</p>
<p>Here are some useful preferences:</p>
<pre class="brush: js">
// this enables marionette which lets you run performance tests
// see https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_performance_tests
user_pref("marionette.defaultPrefs.enabled", true);

// this sets the port for remote debugging your application on the device
user_pref("devtools.debugger.remote-port", 60000);

// this enables the remote debugger
user_pref("devtools.debugger.remote-enabled", true);

// this outputs debug information about the Radio Interface Layer in logcat
user_pref("ril.debugging.enabled", true);
</pre>
<p>This file is read each time you generate a profile. The safest way to be sure that everything is generated is to delete your profile first:</p>
<pre class="brush: bash">
rm -rf profile &amp;&amp; make profile</pre>
<p>Then you can safely use the <code>install-gaia</code> goal.</p>
<h2 id="FAQ">FAQ</h2>
<h3 id="1)_The_device_remains_black_after_a_flash">1) The device remains black after a flash</h3>
<p>This can sometimes happen if you flash the device while it is idle. To remedy this just restart B2G by issuing the following command from the command line:</p>
<p>adb shell stop b2g &amp;&amp; adb shell start b2g</p>
<p>&nbsp;</p>
현재 리비전 복원