build

Building Basic

Everything is command-line driven and structured around directories.

Doing like this allow to

• run the build from the command-line
  $ make
$ ant
$ redbean
• run the build cross-platform
  from Windows, Mac OS X, Linux Ubuntu, etc.
  note: some build will run only under a specific platform
• build in a similar manner for different type of projects
  $ redbean -f build-linux.as3
$ redbean -f build-macosx.as3
• run remote build from the command-line
  on LAN, on VM, on remote server, etc.
  $ ssh zwetan@beta "cd /work/helloworld-cli-linux/; redbean"
$ ssh zwetan@beta "cd /work/helloworld-cli-linux/; sudo build/make-linux-deb"
$ ssh zwetan@gamma "cd /cygdrive/c/work/helloworld-cli-windows/; build/make-windows-deb"
• as long as you have the command-line in place
  and the tooling (build tools, dependencies, SDK, etc.)
  you are free to use whatever code editor/IDE you want

Organisation

Project structure

.          root directory (the name of the project and/or repository)
|_ assets  the shared assets (images, fonts, etc.)
|
|_ build   the build files and utilities
|
|_ src     the source code
|
|_ ...

assets
contains any static and raw assets you may need to transform to build the app.

Few examples:

• an application icon, or many icons.
• a TTF font you need to embed
• a IANA CVS you need converted to an Array in your program

build
contains all the build scripts, commands, build dependencies, build templates, etc.

Few examples:

• from the root of the project you will call
  $ build/make-linux-deb
  to automatically build a Linux executable
  and produce a Debian package
• another command to get your program version
  $ build/getversion
• templates to produce a command-line manual
  /build/templates/man-head.md.tpl
/build/templates/man-body.md.tpl

src
contains the ActionScript 3.0 sources of the program.

Will go more in details later.

the root of the project
is our command control center, we run all command-line tools from this path.

The root will also contains "main build" files.

As a general term I call all those files "the build", but it is important to explain a bit more in details.

• a "main build"
  is the build that compile the program executable
  from src to exe if you prefer
  for example:
  $ ant or $ ant -f build.xml
$ redbean or $ redbean -f build.as3
• a "packaging build"
  is the build sequence that reuse the "main build"
  but also the assets, the build scripts/templates/etc.
  to produce a distribuable package
  for example:
  $ build/make-linux-deb
$ build/make-macosx-pkg
• a "test file"
  is a script meant to run the executable we just built
  once you get an exe you run it to test it
  for example:
  $ test_program run the program executable
  $ test_man run the manual of the program

All those files are located in the root of the project
or are meant to be run from the root of the project (the "packaging builds").

Other files in the root of the projects are documentation files like: LICENSE.md, CHANGELOG.md and README.md.

Auto-generated Directories

When you run a build, some files and directories will be dynamically created.

.
|_ bin-release    all the generated files from the build goes here
|
|_ bin-deploy     the final package goes here
|
|_ man            the command-line manual goes here
|
|_ ...

Specific to a Redtamarin program
When you run the build $ redbean, in general it will generate an ABC or a SWF file in the root of the project.

In details

• the main source file is located under src/
  for example:
  src/helloworld.as
• redbean (which reuse ASC to compile)
  will generate the ABC/SWF file at the same location
  then the main source file
  for example:
  src/helloworld.abc
• the default build.as3
  simply move src/helloworld.abc to the root of the project

Technically, you can move the ABC/SWF file anywhere you want:
in the bin-release/ directory, in another directory, etc.

But we also want an easy workflow to test what we just compiled
and running test_program from the root directory when
the ABC file is also in the root directory is simpler.

It is even better when we also need to load dynamic libraries before running the program (we will see that later).

man
contains our command-line manual template(s).

By default, we will want at least one manual, but you could have 2, 3, etc.

Because it's easier, we use a markdown syntax and pandoc to convert it.

For example:
$ pandoc man/helloworld.1.md -s -t man -o helloworld.1

bin-release
contains all the built and generated files that compose our program.

It is also where we will build the virtual directories for a package.

In fact, if you were thinking that publishing a command-line executable is only publishing one exe file, it is a bit more complicated than that (hence why an automated build that help doing that).

The bin-release can contain a lot of different things, let's consider this directory as "file structure before packaging".

bin-deploy
contains the final package(s) to be deployed/published.

See the pattern ? bin-something, and bin is for binary (in the large sense of the term).

more
if you use certain types of IDE to edit ActionScript 3.0 sources code, those may generate a bin-debug directory.

In general we consider all those bin-something directories as "deletable" or "temporary", for example we would not commit them to a repository.

The source code of the program

The very basic would gives something like

.
|_ src                       all the sources goes here
|   |_ version.properties    the semver of the program
|   |_ helloworld.as         the main file we compile
|   |_ ...                   other sources

And following the same logic as the bin-something directories, we also have the lib-something directories that contains "code libraries".

for example:

• lib-abc
  would contain ABC files
• lib-swc
  would contain SWC files

Special case version.properties

version.major=1
version.minor=0
version.patch=0

We use semantic versioning
format is {major}.{minor}.{patch}.

The program and the build are dependant on this file to know the version of the program.

In general, you need to edit this file manually to update the version of your program.

In some cases a build utilities could update this file automatically before the build.

Note:
this version.properties come from ant builds (using Java)
but I use it in such a way that it is compatible also with
ActionScript 3 programs and build scripts

Special case helloworld.as

the main redtamarin file "wrapper"

include "corsaair/helloworld/App.as";

import corsaair.helloworld.*;
import shell.Program;

var version:Object = {};
include "version.properties";
var versionstr:String = version.major + "." + version.minor + "." + version.patch;

var app:App = new App( versionstr );
    app.main( Program.argv );

This file is about managing the include files for a Redtamarin program.

Just include every single file or library file there.

Note:
see how we include the version.properties file
"as if" it was an AS3 include, so we can reuse it
and inject it as litteral object into the program
constructor.

About library files

A library file is something you add in /src that already include a bunch of individual files.

for example: your program need the ansi library

.
|_ src
|   |_ version.properties
|   |_ helloworld.as
|   |_ ansilib.as          ansi library file
|   |_ encoding
|   |      |_ ansi
|   |           |_ ...     ansilib source files
|   |_ ...

then you edit helloworld.as

include "ansilib.as"

include "corsaair/helloworld/App.as";

import corsaair.helloworld.*;
import shell.Program;

...

ansilib.as already made the work to organise its own includes

include "encoding/ansi/controls.as";
include "encoding/ansi/colors.as";
include "encoding/ansi/backgrounds.as";
include "encoding/ansi/colorize.as";
include "encoding/ansi/colorizeWith.as";
include "encoding/ansi/AnsiString.as";

"ansilib 1.0";

Workflow

TODO