Yulup Development Policy

Revision History
Revision 1.0	2006-05-17	AW
First initial draft.

1. Development Rules

1.1. Methodology

The development of Yulup is test-driven. CppUnit is employed as the testing frame work. Additionally, we use a sub-set of Design-by-Contract, namely pre- and postconditions, to ensure correctness.

1.1.1. Unit Tests

Before implementing a new part of the interface, first write a fixture with CppUnit, and afterwards write the actual business logic.

1.1.2. Design by Contract

Pre- and postconditions are defined in the interface files themselves, and must be implemented in the actual implementation using either assert statements (Java) or NS_PRECONDITON and NS_POSTCONDITION macros from nsDebug.h (see http://lxr.mozilla.org/mozilla1.8.0/source/xpcom/glue/nsDebug.h).

Remember that preconditions can only get weaker in subclasses, and postconditions accordingly can only get stronger.

1.2. Coding Style

C++/Java/JavaScript. Use a tab with of 4 spaces. No tabs allowed.
XML. Use a tab with of 2 spaces. No tabs allowed.

1.3. Coding Practices

C++.

Do not use exceptions. They are not portable.

For further rules, see Mozilla Style Guide and the C++ Portability Guide. They are normative for Yulup.

Use the licensing templates from http://www.mozilla.org/MPL/boilerplate-1.1/.
Java.
- Use camelNotation.
- Use the licensing templates from http://www.mozilla.org/MPL/boilerplate-1.1/.
JavaScript.
- Use camelNotation.
- Prefix formal parameters with "a".
- Prefix globals with "g".
- Use Java-style constants (all CAPS with underscores).
- Use the licensing templates from http://www.mozilla.org/MPL/boilerplate-1.1/.

2. Directory Structure

The directory structure of the source directory is as follows:

./
 |-- mozilla                                          (1)
 |    |-- gecko-sdk                                   (2)
 |    |    |-- PLATFORM                               (3)
 |    |    `-- PLATFORM...
 |    |-- xulrunner                                   (4)
 |    |    |-- bin                                    (5)
 |    |    |    |-- PLATFORM                          (6)
 |    |    |    `-- PLATFORM...
 |    |    `-- src                                    (7)
 |    |         |-- mozilla                           (8)
 |    |         `-- cvsco.log                         (9)
 |    `-- mozilla-tree.config                         (10)
 |-- yulup                                            (11)
 |    |-- bin                                         (12)
 |    |    |-- PLATFORM                               (13)
 |    |    `-- PLATFORM...
 |    |-- pkg                                         (14)
 |    |    |-- PLATFORM                               (15)
 |    |    `-- PLATFORM...
 |    `-- src                                         (16)
 |         |-- backend                                (17)
 |         |    |-- public                            (18)
 |         |    |    `-- Makefile.in
 |         |    |-- src                               (19)
 |         |    |    `-- Makefile.in
 |         |    `-- test                              (20)
 |         |         `-- Makefile.in
 |         |-- connector                              (21)
 |         |-- frontend                               (22)
 |         |    |-- public                            (23)
 |         |    |    `-- Makefile.in
 |         |    |-- src                               (24)
 |         |    |    `-- Makefile.in
 |         |    |-- test                              (25)
 |         |    |    `-- Makefile.in
 |         |    `-- variants                          (26)
 |         |         |-- browser                      (27)
 |         |         |    |-- public                  (28)
 |         |         |    |    `-- Makefile.in
 |         |         |    |-- src                     (29)
 |         |         |    |    `-- Makefile.in
 |         |         |    `-- test                    (30)
 |         |         |         `-- Makefile.in
 |         |         |-- standalone                   (31)
 |         |         `-- web                          (32)
 |         |-- Makefile.in
 |         `-- install.rdf                            (33)
 `-- Makefile                                         (34)

(1)	The `mozilla` directory contains the Mozilla header files and source code which are needed to link against. This is a CVS checkout of the target Mozilla branch for this specific Yulup branch. Note that the contents of this directory are READ-ONLY. This means: You MUST NOT modify the contents of this directory directly. If the contents are modifed, we cannot guarantee anymore that Yulup builds against the targeted Mozilla branch. You MUST NOT execute `make` in this directory. The Mozilla platform employs a modified make infrastructure. Executing plain `make` screws up the tree beyond repair. You MUST NOT perform a CVS update in this directory. The Mozilla platform employs a custom CVS infrastructure which is driven by make files. Executing plain `cvs up` screws up the tree beyond repair. In order to update the Mozilla tree, issue `make mozilla-update` in the parent directory of `mozilla` (cf. Build Infrastructure). Note that this operation may only be performed by an authorised developer.
(7)	The `mozilla/xulrunner/src` directory contains the Mozilla XULRunner tree from which the Gecko SDK is built. Note that this directory is about 306 MB in size.
(10)	The `mozilla-tree.config` contains the branch string of the Mozilla tree to checkout and update. Change the string in this file if you want to switch to a different branch of the Mozilla tree (but first issue `make mozilla-remove` to make sure that the branches do not mix up).
(11)	The `yulup` directory contains all files related to Yulup. Although `mozilla` is of course needed to build Yulup, those files are not an integral part of Yulup.
(12)	The `yulup/bin` directory contains the object files of the Yulup module.
(14)	The `yulup/pkg` directory contains an installable XPI file of Yulup.
(16)	The `yulup/src` directory contains the Yulup sources.
(23)	The `yulup/src/frontend/public` directory contains the IDL files to interface with other modules.
(24)	The `yulup/src/frontend/src` directory contains the module source files.
(25)	The `yulup/src/frontend/test` directory contains the unit test source files.
(33)	The `yulup/src/install.rdf` file contains the information necessary to install Yulup as an XPI extension.
(34)	The `Makfile` contains the central logic of the build infrastructure. For instructions on how to use it, see Build Infrastructure.

3. Build Infrastructure

The central tool for building Yulup is the make file in the top-level source directory. It supports the following targets:

Default Target. The default target builds Yulup and places the objects in yulup/bin.
pkg. The pkg target builds Yulup and creates an installable XPI file in yulup/pkg.
clean. The clean targets removes the object files in yulup/bin and deletes the XPI package in yulup/pkg.
mozilla-checkout. The mozilla-checkout target first removes the Mozilla tree in mozilla/xulrunner and then performs a fresh checkout of the branch set in mozilla-tree.conf.

Do NOT exercise this target unless you know what you are doing and are authorised to do so.
mozilla-update. The mozilla-update target updates the Mozilla tree in mozilla.

Do NOT exercise this target unless you know what you are doing and are authorised to do so.
mozilla-build-gecko-sdk. The mozilla-build-gecko-sdk target builds and installs the platform-specifc Gecko SDK in mozilla/gecko-sdk/PLATFORM, where PLATFORM is a string based on the architecture and the operating system currently running on your build host.
mozilla-remove. The mozilla-remove target deletes the complete Mozilla tree in mozilla.

Do NOT exercise this target unless you know what you are doing and are authorised to do so.
mozilla-clean. The mozilla-clean target cleans the Mozilla tree in mozilla/xulrunner.

Do NOT exercise this target unless you know what you are doing and are authorised to do so.

Andreas Wuest