mirror of
https://github.com/nasa/openmct.git
synced 2024-12-24 07:16:39 +00:00
becf05d4a6
Add top level README file describing, in broad terms, the structure of the project. In particular, this documents the naming conventions which support build and test, and provides a short summary of how these both run. WTD-519.
92 lines
3.9 KiB
Markdown
92 lines
3.9 KiB
Markdown
# Open MCT Web
|
|
|
|
Open MCT Web is a web-based platform for mission operations user interface
|
|
software.
|
|
|
|
## Bundles
|
|
|
|
A bundle is a group of software components (including source code, declared
|
|
as AMD modules, as well as resources such as images and HTML templates)
|
|
that are intended to be added or removed as a single unit. A plug-in for
|
|
Open MCT Web will be expressed as a bundle; platform components are also
|
|
expressed as bundles.
|
|
|
|
A bundle is also just a directory which contains a file `bundle.json`,
|
|
which declares its contents.
|
|
|
|
The file `bundles.json` (note the plural), at the top level of the
|
|
repository, is a JSON file containing an array of all bundles (expressed as
|
|
directory names) to include in a running instance of Open MCT Web. Adding or
|
|
removing paths from this list will add or remove bundles from the running
|
|
application.
|
|
|
|
### Bundle Contents
|
|
|
|
A bundle directory will contain:
|
|
|
|
* `bundle.json`, the declaration of the bundles contents.
|
|
* A source code directory, named `src` by convention. This contains all
|
|
JavaScript sources exposed by the bundle. These are declared as
|
|
AMD modules.
|
|
* A directory for other resources, named `res` by convention. This
|
|
contains all HTML templates, CSS files, images, and so forth to be
|
|
used within a given bundle.
|
|
* A library directory, named `lib` by convention. This contains all
|
|
external libraries used and/or exposed by the bundle.
|
|
* A test directory, named `test` by convention. This contains all unit
|
|
tests declared for the bundle, as well as a `suite.json` that acts
|
|
as a listing of these dependencies. See the section on unit testing
|
|
below.
|
|
|
|
Following these bundle conventions is required, at present, to ensure
|
|
that Open MCT Web (and its build and tests) execute correctly.
|
|
|
|
## Tests
|
|
|
|
The repository for Open MCT Web includes a test suite that can be run
|
|
directly from the web browser, `test.html`. This page will:
|
|
|
|
* Load `bundles.json` to determine which bundles are in the application.
|
|
* Load `test/suite.json` to determine which source files are to be tested.
|
|
This should contain an array of strings, where each is the name of an
|
|
AMD module in the bundle's source directory. For each source file:
|
|
* Code coverage instrumentation will be added, via Blanket.
|
|
* The associated test file will be loaded, via RequireJS. These will
|
|
be located in the bundle's test folder; the test runner will presume
|
|
these follow a naming convention where each module to be tested has a
|
|
corresponding test module with the suffix `Spec` in that folder.
|
|
* Jasmine will then be invoked to run all tests defined in the loaded
|
|
test modules. Code coverage reporting will be displayed at the bottom
|
|
of the test page.
|
|
|
|
At present, the test runner presumes that bundle conventions are followed
|
|
as above; that is, sources are contained in `src`, and tests are contained
|
|
in `test`. Additionally, individual test files must use the `Spec` suffix
|
|
as described above.
|
|
|
|
An example of this is expressed in `platform/framework`, which follows
|
|
bundle conventions.
|
|
|
|
## Build
|
|
|
|
Open MCT Web includes a Maven command line build. Although Open MCT Web
|
|
can be run as-is using the repository contents (that is, by viewing
|
|
`index.html` in a web browser), and its tests can be run in-place
|
|
similarly (that is, by viewing `test.html` in a browser), the command
|
|
line build allows machine-driven verification and packaging.
|
|
|
|
This build will:
|
|
|
|
* Check all sources (excluding those in directories named `lib`) with
|
|
JSLint for code style compliance. The build will fail if any sources
|
|
do not satisfy JSLint.
|
|
* Run unit tests. This is done by running `test.html` in a PhantomJS
|
|
browser-like environment. The build will fail if any tests fail.
|
|
* Package the application as a `war` (web archive) file. This is
|
|
convenient for deployment on Tomcat or similar. This archive will
|
|
include sources, resources, and libraries for bundles, as well
|
|
as the top-level files used to initiate running of the application
|
|
(`index.html` and `bundles.json`).
|
|
|
|
Run as `mvn clean install`.
|