From f0d785f5d07be00a9e200259cd7093c8f1ae8269 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 9 Mar 2011 23:19:00 -0500 Subject: [PATCH] Added information on source tree --- doc/integration.texi | 220 +++++++++++++++++++++++++++++++++++++++++++ doc/manual.texi | 6 +- 2 files changed, 224 insertions(+), 2 deletions(-) create mode 100644 doc/integration.texi diff --git a/doc/integration.texi b/doc/integration.texi new file mode 100644 index 0000000..56c890c --- /dev/null +++ b/doc/integration.texi @@ -0,0 +1,220 @@ +@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. + diff --git a/doc/manual.texi b/doc/manual.texi index 309bca0..77759fb 100644 --- a/doc/manual.texi +++ b/doc/manual.texi @@ -42,11 +42,13 @@ This manual is for ease.js, version 0.1.0-pre. @end ifnottex @menu -* About:: About the project -* License:: Document License +* About:: About the project +* Integration:: How to integrate ease.js into your project +* License:: Document License @end menu @include ./about.texi @include ./license.texi +@include ./integration.texi @bye