Source Tree is now an appendix in manual
Mike Gerwitz
parent
98102ffff2
commit
2662e4f30f
|
|
@ -17,209 +17,10 @@ downloading pre-built packages. Depending on what you are doing, you may not
|
|||
have to build ease.js at all.
|
||||
|
||||
@menu
|
||||
* Source Tree:: Describes the project source tree
|
||||
* Building:: How to build ease.js
|
||||
* Including:: Including ease.js in your own project
|
||||
@end menu
|
||||
|
||||
@node Source Tree
|
||||
@section Source Tree
|
||||
Before building, you need to get a hold of the source tree. Either download an
|
||||
archive (tarball, zip, etc), or clone the Git repository. We will do the latter.
|
||||
Feel free to clone from your favorite source.
|
||||
|
||||
@example
|
||||
# to clone from GitHub (do one or the other, not both)
|
||||
$ git clone git://github.com/mikegerwitz/easejs
|
||||
|
||||
# to clone from Gitorious (do one or the other, not both)
|
||||
$ git clone git://gitorious.org/easejs/easejs.git
|
||||
@end example
|
||||
|
||||
The repository will be cloned into the @file{./easejs} directory. Let's take a
|
||||
look around.
|
||||
|
||||
@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 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 tests
|
||||
* Tools Directory:: Contains build tools
|
||||
@end menu
|
||||
|
||||
@node Root Directory
|
||||
@subsection 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.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 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.
|
||||
@end table
|
||||
|
||||
These files will be discussed in further detail when they are actually used.
|
||||
|
||||
|
||||
@node Doc Directory
|
||||
@subsection 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
|
||||
@subsection Lib Directory
|
||||
The @file{lib/} directory contains the source code for the project. Each source
|
||||
file represents a single CommonJS module and is written in JavaScript.
|
||||
|
||||
@table @file
|
||||
@item class.js
|
||||
The main Class module. This contains all the functionality necessary to declare
|
||||
and extend classes, implement interfaces, etc. This is the bulk of ease.js.
|
||||
|
||||
@item interface.js
|
||||
Allows declaration and extension of Interfaces.
|
||||
|
||||
@item member_builder.js
|
||||
Responsible for building class members.
|
||||
|
||||
@item propobj.js
|
||||
Builds the internal property instance object that is passed around to methods of
|
||||
specific class instances. This is the magic behind visibility support, and
|
||||
therefore encapsulation.
|
||||
|
||||
@item prop_parser.js
|
||||
Parses property strings. Note that the name refers to JavaScript properties,
|
||||
which are any members of an object. Therefore, this module works on all members.
|
||||
|
||||
@item util.js
|
||||
General utility functions for property parsing, object cloning, browser
|
||||
fallbacks, etc.
|
||||
@end table
|
||||
|
||||
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
|
||||
@subsection 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 ensure that bugs are not introduced for
|
||||
anything that has been covered. This 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.
|
||||
|
||||
All tests 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. The
|
||||
tests are written in JavaScript and use Node.js's @file{assert} module. They may
|
||||
be run individually or at once during the build process.
|
||||
|
||||
Tests are discussed later on in this chapter.
|
||||
|
||||
|
||||
@node Tools Directory
|
||||
@subsection 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 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.
|
||||
@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.
|
||||
|
||||
|
||||
@node Building
|
||||
@section Building
|
||||
|
|
|
|||
|
|
@ -44,11 +44,13 @@ This manual is for ease.js, version 0.1.0-pre.
|
|||
@menu
|
||||
* About:: About the project
|
||||
* Integration:: How to integrate ease.js into your project
|
||||
* Source Tree:: Overview of source tree
|
||||
* License:: Document License
|
||||
@end menu
|
||||
|
||||
@include ./about.texi
|
||||
@include ./integration.texi
|
||||
@include ./source-tree.texi
|
||||
@include ./license.texi
|
||||
|
||||
@bye
|
||||
|
|
|
|||
|
|
@ -0,0 +1,208 @@
|
|||
@c This document is part of the ease.js manual
|
||||
@c Copyright (c) 2011 Mike Gerwitz
|
||||
@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
|
||||
@c or any later version published by the Free Software Foundation;
|
||||
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
||||
@c Texts. A copy of the license is included in the section entitled ``GNU
|
||||
@c Free Documentation License''.
|
||||
|
||||
@node Source Tree
|
||||
@appendix Source Tree
|
||||
Before building, you need to get a hold of the source tree. Either download an
|
||||
archive (tarball, zip, etc), or clone the Git repository. We will do the latter.
|
||||
Feel free to clone from your favorite source.
|
||||
|
||||
@example
|
||||
# to clone from GitHub (do one or the other, not both)
|
||||
$ git clone git://github.com/mikegerwitz/easejs
|
||||
|
||||
# to clone from Gitorious (do one or the other, not both)
|
||||
$ git clone git://gitorious.org/easejs/easejs.git
|
||||
@end example
|
||||
|
||||
The repository will be cloned into the @file{./easejs} directory. Let's take a
|
||||
look around.
|
||||
|
||||
@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 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 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.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 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.
|
||||
@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 and is written in JavaScript.
|
||||
|
||||
@table @file
|
||||
@item class.js
|
||||
The main Class module. This contains all the functionality necessary to declare
|
||||
and extend classes, implement interfaces, etc. This is the bulk of ease.js.
|
||||
|
||||
@item interface.js
|
||||
Allows declaration and extension of Interfaces.
|
||||
|
||||
@item member_builder.js
|
||||
Responsible for building class members.
|
||||
|
||||
@item propobj.js
|
||||
Builds the internal property instance object that is passed around to methods of
|
||||
specific class instances. This is the magic behind visibility support, and
|
||||
therefore encapsulation.
|
||||
|
||||
@item prop_parser.js
|
||||
Parses property strings. Note that the name refers to JavaScript properties,
|
||||
which are any members of an object. Therefore, this module works on all members.
|
||||
|
||||
@item util.js
|
||||
General utility functions for property parsing, object cloning, browser
|
||||
fallbacks, etc.
|
||||
@end table
|
||||
|
||||
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 ensure that bugs are not introduced for
|
||||
anything that has been covered. This 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.
|
||||
|
||||
All tests 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. The
|
||||
tests are written in JavaScript and use Node.js's @file{assert} module. They may
|
||||
be run individually or at once during the build process.
|
||||
|
||||
Tests are discussed later on in this chapter.
|
||||
|
||||
|
||||
@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 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.
|
||||
@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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue