205 lines
8.1 KiB
Plaintext
205 lines
8.1 KiB
Plaintext
@c This document is part of the GNU ease.js manual.
|
|
@c Copyright (C) 2011, 2013, 2014 Free Software Foundation, Inc.
|
|
@c Permission is granted to copy, distribute and/or modify this document
|
|
@c under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
@c any later version published by the Free Software Foundation; with no
|
|
@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
|
@c A copy of the license is included in the section entitled ``GNU Free
|
|
@c Documentation License''.
|
|
|
|
@node Source Tree
|
|
@appendix Source Tree
|
|
You should already have gotten a hold of the source tree
|
|
(@pxref{Getting GNU ease.js}). If not, please do so first and feel free to
|
|
follow along.
|
|
|
|
@example
|
|
$ cd easejs
|
|
$ ls -d */
|
|
doc/ lib/ test/ tools/
|
|
@end example
|
|
|
|
The project contains four main directories in addition to the root
|
|
directory:
|
|
|
|
@table @file
|
|
@item ./
|
|
The root directory contains basic project files, such as @file{README},
|
|
@file{Makefile} and @file{index.js}.
|
|
|
|
@item doc/
|
|
Contains documentation source files (you are currently reading part of it -
|
|
the manual).
|
|
|
|
@item lib/
|
|
Contains the actual source code for the various modules.
|
|
|
|
@item test/
|
|
Contains unit and performance tests.
|
|
|
|
@item tools/
|
|
Various tools used during build process.
|
|
@end table
|
|
|
|
Let's take a look at each directory in more detail.
|
|
|
|
@menu
|
|
* Root Directory:: Contains basic project files
|
|
* Doc Directory:: Contains source documentation files (manual)
|
|
* Lib Directory:: Contains project source files (modules)
|
|
* Test Directory:: Contains unit and performance tests
|
|
* Tools Directory:: Contains build tools
|
|
@end menu
|
|
|
|
@node Root Directory
|
|
@section Root Directory
|
|
The root directory contains basic project files for common operations.
|
|
|
|
@table @file
|
|
@item index.js
|
|
This file is loaded automatically when @samp{require( 'easejs' )} is used.
|
|
|
|
@item LICENSE
|
|
Contains the project license.
|
|
|
|
@item Makefile
|
|
Invoked by the @command{make} command. Used for building ease.js.
|
|
|
|
@item package.json
|
|
Used by @command{npm}, a package manager for Node.js, to automate
|
|
installation.
|
|
|
|
@item README.hacking
|
|
Useful information for those looking to modify/contribute to the project.
|
|
|
|
@item README.md
|
|
Serves as a quick reference for the project, in markdown@footnote{See
|
|
@uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was
|
|
chosen because it is displayed nicely on GitHub.
|
|
|
|
@item README.todo
|
|
Incomplete tasks. Future direction of the project. If you're looking to help
|
|
out, take a look at this file to see what needs to be done. (See also the
|
|
bug tracker at @uref{http://easejs.org/bugs}).
|
|
@end table
|
|
|
|
These files will be discussed in further detail when they are actually used.
|
|
|
|
|
|
@node Doc Directory
|
|
@section Doc Directory
|
|
The @file{doc/} directory contains the source files for the manual. The
|
|
source files are in Texinfo@footnote{See
|
|
@uref{http://www.gnu.org/software/texinfo/}.} format. Instructions for
|
|
compiling the documentation are included later in this chapter.
|
|
|
|
API documentation is @emph{not} included in this directory. It is generated
|
|
from the source code.
|
|
|
|
|
|
@node Lib Directory
|
|
@section Lib Directory
|
|
The @file{lib/} directory contains the source code for the project. Each
|
|
source file represents a single CommonJS module, often containing a
|
|
prototype, and is written in JavaScript. Additional information about each
|
|
of the modules can be found in the header of each file.
|
|
|
|
Unless you are developing for ease.js, you needn't concern yourself with
|
|
these files. @file{index.js}, in the root directory, contains mappings to
|
|
these files where necessary, exposing the useful portions of the API for
|
|
general use. You can use ease.js without even recognizing that the
|
|
@file{lib/} directory even exists.
|
|
|
|
|
|
@node Test Directory
|
|
@section Test Directory
|
|
The @file{test/} directory contains all the unit tests for the project.
|
|
ease.js follows a test-driven development model; every single aspect of the
|
|
framework is tested to ensure that features work as intended both
|
|
server-side and across all supported web browsers. The tests also serve as
|
|
regression tests, ensuring that bugs are not introduced for anything that
|
|
has been covered. These tests should also give outside developers
|
|
confidence; if a developer makes a modification to ease.js and does not
|
|
cause any failing tests, it's likely that their change didn't have negative
|
|
consequences on the integrity of the framework.
|
|
|
|
ease.js is currently in a transition period in regards to the style of the
|
|
test cases. Tests written in the original format are prefixed with
|
|
@samp{test-}, followed by the name of the module, followed optionally by the
|
|
specific part of the module that is being tested. Newer test cases are
|
|
prefixed with the prototype name of the unit being tested, followed by
|
|
@samp{Test.js}. If there are a number of test cases for a given prototype,
|
|
any number of tests will be included (with the same suffix) in a directory
|
|
with the same name as the prototype. The tests are written in JavaScript and
|
|
use Node.js's @file{assert} module. Newer tests use a test case system that
|
|
was developed to suit the needs of the project (still using the
|
|
@file{assert} module). They may be run individually or all at once during
|
|
the build process.
|
|
|
|
Developers interested in contributing to ease.js can aid in this transition
|
|
process by helping to move all @file{test-*} tests over to the new test case
|
|
format.
|
|
|
|
In addition, there exists a @file{test/perf/} directory that contains
|
|
performance tests used for benchmarking.
|
|
|
|
|
|
@node Tools Directory
|
|
@section Tools Directory
|
|
The @file{tools/} directory contains scripts and data necessary for the
|
|
build process. The tools are shell scripts that may be run independently of
|
|
the build process if you find them to be useful. The remaining files are
|
|
data to accompany those tools.
|
|
|
|
@table @file
|
|
@item combine
|
|
Concatenates all the modules and wraps them for client-side deployment. If
|
|
requested, the tests are also wrapped and concatenated so that they may be
|
|
run in the web browser. The contents are stripped of trailing commas using
|
|
the @command{rmtrail} tool. The resulting file is @emph{not} minified; the
|
|
user can use whatever process he/she wishes to do so. In the future,
|
|
minification will be part of the build script.
|
|
|
|
@item rmtrail
|
|
Removes trailing commas from object and array definitions. Reads from
|
|
standard in. @emph{This script is not intelligent.} It was designed to work
|
|
with ease.js. It does not, for example, check to ensure that it is not
|
|
removing commas from within strings. This would not be a difficult addition,
|
|
but is currently unnecessary. Use caution when using this tool outside of
|
|
ease.js.
|
|
|
|
@item minify.js
|
|
Responsible for receiving input from stdin and writing minified output to
|
|
stdout. This script uses UglifyJS to minify source files for distribution,
|
|
improving download times.
|
|
|
|
@item browser-test.html
|
|
Skeleton page to be used after the build process. Runs ease.js unit tests in
|
|
the web browser and reports any failures. This is very important to ensure
|
|
that ease.js operates consistently between all supported browsers. The tests
|
|
that are run are the same exact tests that are run server-side.
|
|
|
|
@item combine-test.tpl
|
|
Contains a client-side implementation of any modules required for testing.
|
|
This file contains mainly assertions. It is included by the
|
|
@command{combine} script when tests are requested.
|
|
|
|
@item combine.tpl
|
|
Contains the basic functionality required to get CommonJS modules working
|
|
client-side. This is a very basic implementation, only doing what is
|
|
necessary for ease.js to work properly. It is not meant to be a solution for
|
|
all of your client-side CommonJS problems.
|
|
|
|
@item license.tpl
|
|
Contains the license that is to appear atop every combined file, including
|
|
minified. The original text must remain in tact. If you make changes to the
|
|
source code, you are welcome to add additional text. See the @file{LICENSE}
|
|
file in the root directory for more information on what is permitted.
|
|
@end table
|
|
|
|
While the tools may be useful outside of ease.js in some regard, please note
|
|
that they have been tailored especially for ease.js. They do not contain
|
|
unnecessary features that ease.js does not need to make use of. Therefore,
|
|
you may need to adapt them to your own project and individual needs should
|
|
you decide to use them in your own projects.
|