easejs/doc/integration.texi

@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 Integration
@chapter Integrating ease.js

Before diving into ease.js, let's take a moment to get you set up. How ease.js
is integrated depends on how it is being used - on the server or in the client
(web browser). You may also wish to build ease.js yourself rather than
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
@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:

@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.