This document explains how to compile Alpha from the sources.
It contains detailed explanations in order to compile the necessary pieces coming into the Alpha application.
The building process is entirely automated and only one instruction is necessary to launch it. The script controlling this process takes care of everything, retrieving the necessary external sources from the internet, building the various pieces, installing them in the final application, etc.

Prerequisites

OS X version

The version of your Mac OS X system must be 10.9 (Mavericks) or greater.

Apple developer tools

You will need to install the Apple developer tools (aka Xcode) in order to have all the necessary compiling environment. Go to the Xcode download page at the Apple Developer Site to get and install Xcode. Xcode is obtained via the AppStore and is free.
You also need to install the command line developer tools which are not included in the Xcode package. On Mac OS X 10.9 (Mavericks), you just have to type the following command in a Terminal window to get them: 
    xcode-select --install

Unix tools

You also need some very standard Unix tools which could be present on your machine. In particular curl and svn are needed to download the sources from the internet in order to build some Tcl extensions and utilities included in Alpha. In order to compile Aida (which is an utility needed to generate Alpha's documentation), you need to install some additional tools: autoheader and autoconf. Use the command which to check if these tools are present on your machine: if they are, this command will return the path, otherwise it returns an empty string. For instance: 
    which autoconf
If any of the preceding tools is missing, the easiest way to install it is to use MacPorts (see the MacPorts Project site). Assuming MacPorts is installed on your machine and you want to install autoconf, the command is: 
    sudo port -v install autoconf

All set

Once everything is installed on your machine, you are ready to compile Alpha.

The guts of Alpha

The Alpha application, like most applications on Mac OS X, is a bundled application. This means that it contains in a single object all the resources it needs to work properly. It looks like a file when seen in the Finder but, as a matter of fact, it is a directory containing various subdirectories with different kinds of resources. All you need to know in order to understand what follows is that Alpha contains not only the executable binary (usually referred to as the core) but also several important external libraries and tools: The AlphaTcl library is written in Tcl and does not have to be compiled. It is just copied inside the application's bundle.
The Tcl framework and the Tcl extensions are technically shared libraries written in the C language and they have to be compiled. You will usually compile them only the first time you build Alpha.
The Tcl framework provides the Tcl interpreter included in Alpha.
The Tcl extensions bring additional capacities. Alpha currently embeds the following Tcl extensions:
The Aida compiler is necessary to generate Alpha's documentation and help files. Like the extensions, it has to be built only the first time.
All the resources described above are free and can be obtained from the internet. This may seem daunting at first sight but you do not have to fetch anything yourself, every step is automated. The build process described in the following sections takes care of retrieving all the necessary parts and assembling them in the final product.

Downloading the sources

Your first step will be to download the sources for the project.
Alpha is an Open Source project and is hosted on SourceForge (see Alpha's homepage). All the source code for the core and the AlphaTcl library is under version control and is stored in a Subversion repository.
To download the sources from the repository, you need a terminal window. Open one by launching the Terminal application (located in the Utilities subfolder of the Applications folder). In this window, use the cd command to go to the directory where you want to download the Alpha sources. For instance, if you want the sources to be stored in an Documents/Alpha folder (which you have already created), type the following command: 
cd Documents/Alpha
Then execute the following command (checkout can be abbreviated as co): 
svn checkout https://svn.code.sf.net/p/alphacocoa/code/Current
This command will create a new directory named Current inside the Alpha folder containing the latest version of the source code.
Once you have download the Alpha sources for the first time, the structure of the Alpha folder should look something like this:
Alpha download directory
You are now ready to compile Alpha.

A tour of the source tree

At the top level of the Alpha folder, there are initially three subfolders: Branches, Current and Tags. The Branches and Tags folders are not important for the present purpose, only the Current folder is concerned to compile Alpha. This is the main trunk of development. Its hierarchy looks something like this (some directories may be missing and will be automatically created later): 
--- Current
        |--- Core
        |   |   |--- Alpha.xcodeproj
        |   |   |--- Resources
        |   |   |--- Sources
        |   |--- Doc
        |   |--- Libraries
        |   |   |--- AidaLib
        |   |   |--- AlphaTcl
        |   |   |--- Binaries
        |   |   |--- Encodings
        |   |   |--- Extensions
        |   |   |--- Frameworks
        |   |--- Tests
        |   |--- Tools
        |   |--- Utils
        |       |--- AlphaColors
        |       |--- DiffBOA
Here is a description of the subfolders of the Current folder : The AlphaTcl subfolder of the Libraries folder looks something like this: 
--- AlphaTcl
   |--- Examples
   |--- Help
   |--- Tcl
   |   |--- Completions
   |   |--- Menus
   |   |--- Modes
   |   |--- Packages
   |   |--- SystemCode
   |--- Tools
If you are already familiar with AlphaTcl, you will recognize the usual structure.
Initially, the Binaries, Frameworks and Extensions directories are missing or empty. They will be progressively populated when you start compiling the various components.
The Extensions subfolder of the Libraries folder can contain different versions of the Tcl extensions. Once the extensions have been compiled, it might look something like this: 
--- Extensions
   |--- Memchan2.3
   |--- Mk4Tcl2.4.9.7
   |--- TclAddressBook1.2.4
   |--- TclAE2.0.5
   |--- TclAppleScript2.0
   |--- TclGestalt1.1
   |--- tcllib1.15
   |--- TclResource1.3
   |--- TclSpeech2.0
   |--- TclX8.4
   |--- Tdom0.8.3
   |--- Tnc0.3.0
   |--- Vfs1.3
The Frameworks subfolder of the Libraries folder can contain different versions of the embedded frameworks (currently only the Tcl framework but there might be others in the future). Once they have been compiled, it might look something like this: 
--- Frameworks
   |--- Tcl
       |--- 8.5.11
       |--- 8.6.2

Compiling Alpha

There are two methods to compile Alpha: using a Makefile, or using the Xcode project. The easiest method is the Makefile because it just amounts to typing the word make on the command line and requires no knowledge about the Xcode application and its complex interface.
If you compile Alpha for the first time and thus need to build all the external libraries, the only valid method is the Makefile. You cannot build the external libraries from the Xcode project.
Using the Xcode project file will be the preferred method if later you want to contribute to the development of the core or to debug the application. But you will have to get used to its interface and its working flow.
Note that you do not have to compile the entire application every time something changes in the source code of the project. The external libraries (frameworks, Tcl extensions and utilities), once compiled, are stored in the Libraries folder (inside the Alpha sources) and will not need to be rebuilt until a new version is released. If one of them needs updating, it can be rebuilt separately.

Compiling Alpha with the make file

The compilation of all the different parts of Alpha is driven by a Makefile. This file contains sets of instructions known as targets indicating how to execute the different tasks involved by this process. You will never have to understand how it works under the hoods. All you have to know is that in order to execute a target of a Makefile, you just have to execute the command make in a Terminal window followed by the name of the target.
So we are now going to compile Alpha from scratch. The command make is in general followed by the name of a target, but if nothing is specified the first target of the Makefile is used as a default and is executed which is just what we need now. In the Terminal window which was opened in the Downloading the sources section, change the directory to go to the Current subdirectory like this: 
    cd AlphaCocoa/Current
then type the command: 
    make
Terminal window to compile Alpha's sources
That's all there is to it. This command will launch the whole process. If you compile for the first time, it takes approximately 10 minutes to complete. You will see a lot of output on the screen. The command will successively: If no error occurs, you will see a victory message announcing that the Alpha application has been successfully built.

Location of the built application

So where is it ? The Xcode project creates a directory named build in the Current directory. This build directory has a subdirectory named Debug which contains Alpha as showed on the following image.
Alpha in the Finder
The exact path is indicated anyway at the end of the compilation. You can also find it by typing the following command: 
    make app-path
To be more precise the subdirectory of the build directory containing the built product is named after the current configuration of the Alpha target in the Xcode project. It could be Debug or Release.
You can launch the application by typing the following command: 
    make open-app
or by double-clicking on its icon in the Finder as usual.
The next section also explains how to find the built product from the Xcode project.
If you would prefer the newly built application to be in the Applications folder, you can execute the following command in order to copy it thereto: 
    make install-app
There is no necessity to do so though and you can launch Alpha from any location.
The compilation of the frameworks, the extensions and the utilities takes place in a folder named Externals located at the top level of the Alpha top directory (at the same level as the Current, Branches and Tags folders). The Externals folder is just a temporary location where the sources are imported and built. You may throw it away when everything is finished: the products of these compilations won't be lost and are found in the Libraries subfolder of Current.
The Compiling Specific Pieces section below gives more detailed informations about the available targets and explains how to use the make command more selectively.

Compiling Alpha with the Xcode project

The present section explains how to compile or recompile the core of the application (not the external frameworks, extensions and utilities). If you have been compiling Alpha with the make method, the Xcode project was invoked automatically at some point. You will need to open the Xcode project yourself when you already have a built application and you want to debug it or to make modifications in the core.
The Xcode project lets you compile the core of the application and install the various (already compiled) external libraries in the application's bundle. It is responsible for assembling the final product. You cannot compile the external libraries with the Xcode project, you can just install them.
In order to recompile Alpha's executable (that is to say the source code written in Objective C and located in the Core subfolder of the Current folder), open the Xcode project named Alpha.xcodeproj which is precisely located in the AlphaCocoa/Current/Core subfolder. Everything is already set up for the compilation of the project:
  1. select the target named Alpha as the active target in the Scheme popup menu at the top left of the Xcode window;
  2. select the command Build in the Product menu (or press ⌘B).
These two steps are illustrated on the following image:
Build all from Xcode project
The Xcode project also has several targets (aka schemes) to install the various components in the application's bundle:
All the Install targets assume that the libraries have already been compiled and are present in the Librairies subfolder of the Current folder. The target called InstallAll is an umbrella (aka aggregate) target which executes all the abovementionned targets.
For further development, you will usually select as the active target in the Schemes popup, either the Alpha target if the source code has been modified or the InstallAlphaTcl target if the code of the AlphaTcl library has been updated and you want to transfer it into the application bundle.
Image of the Alpha schemes
The following image explains how to find, from the Xcode project, where the built product is located after compilation. Here are step-by-step instructions:
Alpha product in Xcode

Compiling specific pieces

There are several Makefiles in the source tree: 
    --- Current
       |--- Makefile
       |--- Libraries
       |   |--- Makefile
       |--- Utils
       |   |--- Makefile
       |--- Doc
           |--- Makefile

The Makefile located in the Current folder is the master Makefile and it is the one you should use. The others are called from the master when necessary.
The master Makefile is not used only to build the entire application. It has a much finer granularity and can also perform very specific tasks, like recompiling a particular extension, generating a particular component. This is done by specifying an appropriate target in the make command.
On the other hand, most of the rules defined to build the different components of Alpha are implemented via shell scripts which are invoked transparently by the make command. These scripts are located in the Tools subdirectory of the Current directory. It is possible to use them directly.
The following sections explain the different make rules and how to use the build scripts directly.

The Makefile rules

The current section explains more advanced uses of the Makefile driving the build process of Alpha. It assumes that you have already retrieved Alpha's sources from the Subversion repository at SourceForge. See the Downloading the sources section if this is not the case.
There are many different ways to use Alpha's Makefile depending on which part of the application you want to build or rebuild. The various possibilities are known as targets which are sets of rules. You executed a target from the Terminal with the make command followed by the name of the target.
The make command must always be executed in a Terminal window from the directory where the Makefile is located. The master Makefile for Alpha is in the Current folder. Use the cd command in the Terminal window to go to the Current folder: 
    cd /path/to/folder/Alpha/Current
with the appropriate path.
The make command without argument executes the default target which builds everything from scratch. You use it only the first time as explained previously.
Later you will not have to recompile all the components but only the elements which have changed. There are targets for all these elements. You can get more information about the available targets by typing 
    make help
Here help is also a target which prints the usage of the make command in this directory.
All the target names are in lowercase. Here are a few examples.
To compile only the core, the command is: 
    make core
To retrieve the latest AlphaTcl library from the Subversion repository: 
    make alphatcl
To build a specific library: 
    make lib-[name]
where you replace [name] by the appropriate library name. The possible extension names are: memchan, mk4tcl, tclae, tcladdressbook (or tclab), tclapplescript (or tclas), tclgestalt, tcllib, tclresource, tclspeech, tclx, tdom, vfs. For the Tcl framework, the name of the target is tcl.
For instance: 
    make lib-tclae
    make lib-tcl
To rebuild all the extensions: 
    make extensions
To rebuild all the libraries (frameworks and extensions): 
    make libs
To rebuild all the utilites: 
    make utils
To rebuild only the aida utility: 
    make util-aida
To copy all the components (AlphaTcl library, frameworks, extensions) in the application bundle: 
    make install-components
To copy a specific component in the application (provided it has already been built): 
    make install-[name]
where you replace [name] by the appropriate component name. The possible component names are: alphatcl, tclfmwk, tclextns, icons, utils.
For instance: 
    make install-alphatcl
    make install-tclextns
    make install-icons
To install a particular extension or utility: 
    make install-lib-tclae
    make install-util-aida

The build scripts

This section documents the direct use of the build scripts.
There are shell scripts for building all the components: they take care of downloading the source code from the internet, configuring, compiling, and finally assembling the product as an embedded framework or a Tcl extension. These scripts are invoked automatically by the rules of the Makefile but they can also be executed directly. Invoking the scripts directly instead of using the make command can sometimes be useful because they give access to more fine grained options.
The scripts are located in the Tools subfolder of the Current folder. For instance the script to build the Tcl framework is called buildTclFramework and the script to build the TclAE extension is called buildTclAEExtension.

Build scripts usage


These scripts all share the same syntax which can be displayed using the option -h. For instance:
Build scripts help
The building process of each extension consists of three phases: There is a fourth phase which is the cleaning phase where all the intermediary files produced by the compiler are removed. The options supported by all the build scripts have the following meaning: For instance, the following command will just recompile and install the code, in case the source files have already been download from the internet: 
    ./buildTclAEExtension -s f
The '-s f' option means that it skips the fetch phase.
Compilation is performed in a separate directory called Externals located at the top level of the Alpha source tree. This directory is created by the build scripts and contains subdirectories for all the built products. Built libraries are finally installed in the Librairies subfolder of the Current folder and the Externals folder contains only intermediary files. There is no problem destroying it when the compilation is finished.

Build scripts configuration

How do the build scripts know which version of the external librairies they have to build and where to find the source code ? This is set in a configuration file named buildConfig.inc which is read by all the build scripts. This configuration file is a simple shell script which defines environment variables containing the version number and the URL of the libraries.
If you wish to compile another version of a library (extension, framework, utility), you just have to adjust the corresponding environment variables in the buildConfig.inc file. Nothing has to be changed in the scripts themselves.
The -f and -g options explained in the previous section can also be set at a global level. You can create a configuration file named .alphacocoabuild in your home directory and define there some environment variables: For instance, during the development of Alpha, the configuration file .alphacocoabuild could contain the following definitions (using the bash syntax): 
    #!/bin/bash
    export ALPHA_FAT_BIN=0
    export ALPHA_DEBUG_SYMBOLS=1
These environment variables are supported also if you compile the libraries using the Makefile method rather than the build scripts directly.
Finally you can also specify these variables on the command line when invoking the make command. For instance, to build the TclAE extension as a fat library, you can execute the following command: 
    make lib-tclae ALPHA_FAT_BIN=1
This is the same as executing the following command in the Tools directory: 
    ALPHA_FAT_BIN=1 ./buildTclAEExtension

Updating the sources

You will regularly want to update your sources directory to keep up with the latest changes made in the core or in the AlphaTcl library.
This is very simple. From a Terminal window, change directory to the top Alpha folder and type the following command: 
    svn update
If there were changes in the core sources (inside the Core directory), you will need to recompile Alpha. This is done either from the Xcode project with ⌘R or from the Terminal (positionned in the Current directory) like this: 
    cd Current
    make core
If there were changes in the AlphaTcl library, you will just have to install them in the application. This can be done in the Xcode project by selecting the InstallAlphaTcl target and executing it with ⌘R. Alternatively, you can do this from a Terminal window (in the Current directory as before): 
    make install-alphatcl
It there were changes done in some utility (like aida, or DiffBOA), you can recompile it like this: 
    make util-aida
and then install it like this: 
    make install-util-aida
You will rarely have to update the extensions. The extensions are third party software and their source code is independant from the Alpha project. It this ever happens, see the instructions in the Compiling Specific Pieces section.

Last updated 2019-02-18 17:55:07