fohr/blossom — pull request #57 by clinuz (2012-03-23 20:41:19+00:00)
Title: Packaging

> To replace SC.Module with SC.Package that works with the node build tools and offers a few additional features (while missing a few others).

> All references to SC.Module or the "bundles" have been removed. All references to SC.Plugin were removed (I authored them, they will not work with all of the view layer changes and they required SC.Module).

Interesting features I'd like to point out
--------------------------------------------------------------------------
1. SC.Package is extensible unlike SC.Module. It must be created for an application that wishes to use it - but because it is extensible it can be made to work with any loading system for the contents of the packages. For example, if instead of normal HTTP script/src requests it was desirable to have a remote datastore retrieve them statically or pull them from a database. SC.Package will allow this level of abstraction.
2. BT.Packager allows for dependencies to be noted as a directory that is _not_ a package. If there are a collection of packages that are logically separated from other packages that all depend on each package in the directory, these packages merely need to denote the directory in the tree as the dependency and all packages beneath the directory will be used as dependencies.
3. SC.Package allows for control over which layer(s) of the source are executed. **note this also needs to be addressed because SC.Package now resides in application/system but could be used with just models and potentially from foundation** There are flags available to configure the runtime to only use particular portions of code. See SC.Package documentation for an explanation.

Current TODOs
--
1. Add in callback support
2. Update build tools `buildApp` feature to prepare packages for production

Current outstanding questions
--
1. To add CSS support or not...

Here are the first-pass notes written (documented for BT.Package in the build tools source):

> A package is a logically separated/grouped structure containing
source files that do not necessarily need to be loaded at the
same time as the application. They are processed separately and
handled slightly differently than normal targets.

> A package is implicitly derrived by convention: its location in
the filesystem tree and the existence of a `node` directory that
conains a `package.json` file. Packages can be nested inside any
non-package directory (for organizational purposes) within a
`packages` directory in an application or framework (although
this is not strictly enforced at the moment).

> A directory structure like the following

> `framworks/
---- \__some_framwork/
-------- \__packages/
------------ \__some_package/
---------------- \__node/package.json
------------ \__another_package/
---------------- \__node/package.json
------------ \__a_non_package_dir/
---------------- \__a_package_dir_nested/
-------------------- \__node/package.json`

> would lead to the following packages registered in the system:

> some_framework/some_package
> some_framework/another_package
> some_framework/a_package_dir_nested

> It is important to note that within any namespace (framework or
application or nested framework) a package must have a unique
name but are not required to have unique names across namespaces.

> Packages currently do not support CSS but they do support coffee
script. The structure of code in a package is conventional. At
runtime the application decides what portion of the code retrieved
from the package will be evaluated and executed. Packages do
not support framworks or applications and they will be ignored.
It does differentiate between the directories `controllers`,
`models` and `views`. All other types of directories (not
applications or frameworks) will have their source registered
as `other`. This allows, at runtime, for the application to
include only code for the layer it wishes to expose.

> There are 3 types of packages: core, lazy and demand.

> Core packages are loaded with the main source trunk. They are
processed inline with their housing target. If a framework is
a dependency of an application, packages in the framework will
be processed before the application is loaded. Packages embedded
in an application will be loaded before the core file.

> Lazy packages are loaded automatically after the application has
started but their source was not included with
the application source and is loaded after (assists in alleviating
the need to load and process an entire application at once).

> Demand packages are only loaded when needed but must be
arbitrarily requested.

> Configuration options are set via a specially named file in
a package tree. There is a directory `node` with a `package.json`
file. The properties in the json will be directly merged with the
package object for evaluation during processing. This is where
the type of package is specified by the property `type`. If no
file is provided or no type is available it will be assumed to
be a core package. If the `node` directory is not present, however,
the directory will not be interpreted as a package and skipped.
The `dependencies` property (array) can contain
the name of any packages the current package requires to be loaded
first. Any dependencies must be from within the same framework or
application as a dependence on a package from outside the housing
target/namespace should be specified as a dependency of the target
and not the package.

> A global manifest is generated and included with the source trunk
in the index for an application.

> The client-side class responsible for exposing these packages
is SC.Package. The class can be extended or instantiated as-is
for default behaviors. There are global properties that define
other behaviors of the package system at runtime.