bt_readme.md

SproutCore - Build Tools

SproutCore is a platform for building native look-and-feel applications on the web. This Node JS library includes a copy of the SproutCore JavaScript framework as well as a Node JS-based build system called Build Tools.

Build Tools is a build system for creating static web content. You can supply the Build Tools with a collection of JavaScript, HTML, CSS and image files and it will combine the files into a bundle that are optimized for efficient, cached deliver directly from your server or using a CDN.

Some of the benefits of using the Build Tools versus assembling your own content include:

• Easy maintenance. Organize your source content in a way that is useful for you without impacting performance on loaded apps.

• Automatically versioned URLs. Serve content with long expiration dates while Build Tools handles the cache invalidation for you.

• Dependency management. Divide your code into frameworks; load 3rd party libraries. Build Tools will make sure everything loads in the correct order.

• Packing. Combines JavaScript and CSS into single files to minimize the number of resources you download for each page.

Although Build Tools is intended primarily for building Web applications that use the SproutCore JavaScript framework, you can also use it to efficiently build any kind of static web content, even if SproutCore is not involved.

Install the Build Tools from the source

1. Clone the Build Tools repository

    git clone https://github.com/sproutcore/build-tools.git
   

2. install the Build Tools from that new directory

    npm install
   

#####On Windows:

Make sure that you have Git installed and that the PATH contains C:\Program Files\Git\bin before C:\Program Files\Git\cmd. NPM cannot install the sproutcore dependencies correctly from git repositories if git.exe cannot be found in the PATH.

Run the server

You should now be ready to run the server. From the top directory of your project run:

path-to-the-build-tools/bin/sproutcore serve

Now visit http://localhost:4020/ and click the link to load your app!

The new build tools automatically watch for changes, so just start editing your files and refresh the page to see your changes!

Please join us on #sproutcore on IRC or post a message to the mailing list if you run into any issues!

#####On Windows:

Use only a 32 bit NodeJS (for now). For the rest, the steps on Windows are essentially the same, except that the command to start the buildtools is:

node path-to-the-build-tools\bin\sproutcore

It is important that you use forward slashes as path separators in the config files! The buildtools will convert them for you where necessary, but that doesn't work the other way around.

You might run into a problem where running npm install in the getting-started folder immediately returns an error. This is caused by the way git has been installed on your system, where %PROGRAMFILES%\git\cmd is put into the path, but not %PROGRAMFILES%\git\bin. NPM uses child processes which cannot execute .cmd files, so you will have to see whether it is indeed in your path by typing:

echo %PATH%

If C:\Program Files\git\bin is not in your path, you can put it in by doing

set PATH=%PROGRAMFILES%\git\bin;%PATH%

How the Build Tools server works

When you run the command sproutcore serve, Build Tools will execute the project sc_config file in the root of your project directory.

Here is how your project directory should looks like:

├── project/
│   ├── apps/
│   │   ├── app1/
│   │   │   ├── sc_config (app)
│   ├── frameworks/
│   │   ├── rich-text-editor/
│   │   │   ├── sc_config (framework)
│   │   ├── sproutcore/
│   │   │   ├── sc_config (framework)
│   ├── sc_config (project)
│   ├── theme/
│   │   ├── your-theme/
│   │   │   ├── sc_config (theme)

You can choose to have an sc_config inside your app directory, or you can define your app inside the project sc_config. In the first case you will need to use sc_require() in the project sc_config to make the Build Tools aware of your app.

The app 'sc_config' files should contains the configuration of your apps:

// Here is an example of an app configuration
var app1 = BT.AppBuilder.create({
  name: 'app1',
  title: 'App 1', 
  path: 'apps/app1',
  frameworks: [
    'rich-text-editor'
  ],
});

You can see all the available parameters in the appbuilder.js file.

Build Tools will execute these files, and so, create your apps and load all their dependencies. The dependencies of an app are frameworks and modules which should both be in the frameworks directory. For each of these dependencies Build Tools will execute their sc_config and register them as BT.Framework.

BT.addFramework(BT.Framework.extend({
  ref: "rich-text-editor"
}));

You can see all the available parameters in the framework.js file.

Note that if you do not have sproutcore in your frameworks directory, Build Tools will use its own.

Build Tools is now ready to start its server. By default, it listen on localhost on port 4020. If you want to change theses parameters, you have to set a BT.serverConfig variable in your project 'sc_config':

sc_require('apps/app1/sc_config');

BT.serverConfig = {
  host: "localhost",
  port: 4020,
  localOnly: true
};

How Build Tools will build your apps

To build your app, you will have to run the following command sproutcore build [appName]. Build Tools will go throw the same process as if you wanted to start its server, but instead of serving the files of your app, it will save them into a build directory at the root of your project.