File:  [mozdev] / calendarhelp / www / build.html
Revision 1.10: download - view: text, annotated - select for diffs - revision graph
Mon May 23 13:13:09 2005 UTC (12 years, 6 months ago) by whiteley
Branches: MAIN
CVS tags: HEAD
add license info

<h5 class="page-header">Build</h5>


<p>
This page describes how to build CalendarHelp from its source files.
</p>

<h4>Viewing individual source files</h4>
<p>
If you are a writer or translator, you can test an individual source file
by viewing it in a Mozilla browser.
Use the stylesheet <code>draft.css</code> and the bindings <code>draft.xbl</code>
supplied with the English source.
</p>

<p>
You can customize your view of the source files by modifying <code>draft.css</code>.
</p>


<h4>Full build&mdash;overview</h4>
<p>
The builder is a tool that runs in Firefox on Windows.
You might be able to make it run in a different browser or on a different platform,
but these variations are not supported.
</p>

<p>
The builder requires an external ZIP tool from
<a href="http://www.info-zip.org">Info-ZIP</a>.
</p>

<p>
The builder works on local copies of the source files on your computer.
Use a CVS client to get the source files.
The builder does not pull them.
</p>

<p>
For additional information about the builder, see
<a href="buildguide.html">Building help for other projects</a>.
</p>


<h5>Source files</h5>
<p>
You must have copies of all the source files that the builder needs, in the
same directory structure that you find in CVS.
You do not need all the source files for the project&mdash;only the files
that are required for the parts that you want to build.
</p>

<p>
Place the source files in any base directory on your computer.
This base directory corresponds to the <code>src</code> directory in CVS.
You can use any name you like for the base directory&mdash;it does not have to be <code>src</code>.
</p>

<p>
Inside your base directory, keep the directory names and structure the same as in CVS.
</p>

<p>
You can store additional files and directories in most places in the
directory structure without affecting the build,
but there are some exceptions:
<ul>
<li>Do not store extra <code>.xhtml</code> files in the same directory as the
source files for a locale, because the builder will try to index them.</li>
<li>Do not store extra files in the <code>install</code> directory,
because the builder might try to include them in the XPIs.</li>
</ul>
</p>


<h5>What the builder does</h5>
<p>
The builder can build each of CalendarHelp's locales.
</p>

<p>
For each locale, it can build:
<ul>
<li>The indexes</li>
<li>The jar file</li>
<li>The XPI installer</li>
</ul>
</p>

<h5>Indexes</h5>
<p>
There are four indexes.
Three of the indexes are built in each locale.
They correspond to panels in the Help sidebar:
<ul>
<li>Glossary</li>
<li>Main index</li>
<li>Table of contents (ToC)</li>
</ul>
</p>

<p>
The fourth is only built in en-US, because it has no translatable content.
This index maps user-interface elements to help topics:
<ul>
<li>Context map</li>
</ul>
</p>

<p><strong>Note: </strong>
If you find copies of the indexes stored in CVS,
this is by mistake because they are not source files.
If you want to see the indexes, extract them from the jar.
</p>


<h5>Jar file</h5>
<p>
There is one jar for each locale.
The builder stores it in the <code>install</code> directory
for the locale, in the <code>chrome</code> directory there.
For example, it stores the English jar as:
<blockquote>
<code><i>base</i>/calendarhelp/install/en-US/chrome/calendarhelp-en-US.jar</code>
</blockquote>
</p>

<p>
The jars are not stored in CVS.
If you want to see a jar, either install Calendar Help or
extract the jar from the XPI installer.
</p>


<h5>XPI installers</h5>
<p>
There is one XPI installer for each locale.
Each installer works in all the base products:
<ul>
<li>Sunbird</li>
<li>Thunderbird</li>
<li>Firefox</li>
<li>Mozilla Application Suite</li>
<li>Netscape</li>
</ul>
</p>

<p>
The builder stores it in the <code>install</code> directory
for the locale, adding the version string and the locale name to the file name.
For example, it stores the English XPI for version 0.1 as:
<blockquote>
<code><i>base</i>/calendarhelp/install/en-US/calendarhelp-0.1-en-US.xpi</code>.
</blockquote>
</p>

<p>
The XPIs are stored in CVS, but not in this directory.
Instead, they are in the project's downloads directory.
You cannot download them directly from this site.
You can only download them from a mirror site.
</p>


<h4>What you need to build</h4>
<p>
It is likely that you do not need to build everything.
You only need to build the parts that you are interested in, and that depend
on source that has changed.
</p>

<p>
For example, if you are a writer or translator, then it is likely that you
only need to test the changes that you have made.
</p>

<p>
If you build more parts than you really need, it does not do any harm.
It only forces you to download more source files,
and it makes the build process take longer.
</p>

<h5>What writers need to build</h5>
<p>
If you are a writer writing English help, then you can use the builder to test
the changes you have made.
</p>

<p>
You only need to build the en-US locale.
</p>

<p>
You only need to build three of the indexes:
<ul>
<li>Main index</li>
<li>Table of contents</li>
<li>Context map</li>
</ul>
</p>

<p><strong>Note:</strong>
If you are the writer assigned to the glossary, then of course you
only need to build the glossary index and the main index.
</p>

<p>
You need to build the jar.
</p>

<p>
You do not need to build any installer.
You can manually copy the jar, replacing your old version.
</p>


<h5>What translators need to build</h5>
<p>
If you are a translator, then you can use the builder to test
your translation.
</p>

<p>
You only need to build the locale that you are working on.
</p>

<p>
You only need to build three of the indexes:
<ul>
<li>Glossary</li>
<li>Main index</li>
<li>Table of contents</li>
</ul>
</p>

<p>
You need to build the jar.
</p>

<p>
You do not need to build any installer.
You can manually copy the jar, replacing your old version.
</p>



<h4>Installing the builder</h4>
<p>
To install the builder:
<ol>
<li>Download
<a href="http://downloads.mozdev.org/calendarhelp/buildhelp.jar"><code>buildhelp.jar</code></a>
into Firefox's <code>chrome</code> directory.
</li>

<li>
Close Firefox.
</li>

<li>
In Firefox's <code>chrome</code> directory, delete the file
<code>chrome.rdf</code>. (See step 5.)
</li>

<li>
Edit the file <code>installed-chrome.txt</code>, and at the end add this line
(by copying and pasting from here):
<pre>
content,install,url,jar:resource:/chrome/buildhelp.jar!/content/buildhelp/
</pre>
</li>

<li>
Restart Firefox.
It automatically rebuilds <code>chrome.rdf</code>.
</li>

<li>Open the following URL and bookmark it:
<blockquote><pre>
chrome://buildhelp/content
</pre></blockquote>
</li>

</ol>
</p>


<h4>Running the builder</h4>
<p>
To run the builder, open its bookmarked URL.
Specify:
<ul>
<li>The package name (<code>calendarhelp</code>)</li>
<li>A version string (optional)</li>
<li>The base directory where the source files are stored on your local machine</li>
<li>The locales that you want to build</li>
<li>The build steps that you want</li>
</ul>
</p>

<p>
Press the Go button.
Look for error messages in the Status area.
</p>

<p><strong>Note:</strong>
The builder is sensitive to tagging errors in source files,
but it simply fails to process the files without specifying what is wrong.
If this happens, check each source file by viewing it in a Mozilla browser.
The browser identifies the errors.
</p>

<h5 id="options">Defaults and options</h5>
<p>
You can store some builder defaults in <code>buildhelp.ini</code>
in Firefox's <code>res</code> directory.
For example, the file can contain settings like these,
corresponding to fields in the user interface:
<pre>
proj.1=calendarhelp
proj.1.version=0.1
proj.1.base=F:\\Projects
proj.1.subdir=false
</pre>
</p>

<p>
Some builder defaults and options are stored as user preferences.
To change them, go to the URL <code>about:config</code>
and filter on <code>buildhelp</code>.
</p>



FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>