NOTICE This chapter - although still valid to some degree - is now mostly obsoleted by the availability of the packager, which does all of the build process for you. You may skip this if you are not interested in the details and if you do not intent to build using a source code repository.

Deploying an Application

This document should give you detailed step-by-step instructions to enable you to manage the almost automatic build process for deployable applications. Additional information covering the process of application development inside the browser is found in the Smalltalk/X Programmer's Guide.
If you follow these steps and have everything setup correctly, an automatic build for a deployable, self installing application will be a matter of minutes.

Before you start: Prerequisites

ST/X Directory Hierarchy
Before you start, please check, if you have installed ST/X EXACTLY as in the following tree:
```
...
   stxXXX (where XXX is the ST/X release; currently 542)
      stx
	 ...
	 libbasic
	 ...
	 projects
	    ...
	    smalltalk
	    ...
```
Don't be mislead by the name "projects" - your projects will NOT be stored there (for one: it is for exept-projects only; second: the name is a historic leftover).
Your projects will all end up being located in a single directory BESIDE the "stx" directory. Do not create any directory under stx, and do not later edit any files there. These will be under control of ST/X + CVS only. In other words: these are for checkout and build only, not for code files.
Setup CVS (Source Code Versioning System)
This is optional; you can work without a version management system, or even use another one (SVN, Mercurial, Git, etc.). However, CVS was the first such system supported by ST/X and has good tool integration, especially in the browser.
For now, you have to have a CVS source/code repository running on one of your machines in the LAN (can be, but does not have to be the local machine). The CVS should be reachable via the :pserver: protocol. Unix users will probably already find CVS on their system or at least on their distribution medium. Windows users have to download one, or run linux on a real or on a virtual machine. And use that one.
As CVS admin user (not within Smalltalk), create a CVS module, with a useful name. Don't use a stupid name such as "test", "foo" or "demo". We recommend, using your company, your initials or any other meaningful name. If you ever want to share your code with other Smalltalkers, it has to be unique to avoid a conflict. And it will be a lot of stupid, error-prone, manual work to fix this later, because many files will be automatically generated by ST/X later, which depend on this to be consistent.
We are aware of the fact, that CVS is not the best choice, and will both provide support to deploy using other repositories (concrete: SVN or GIT). But for now, that's all we have and you have to live with it, just like we have to ;-)
Get a C-Compiler (Windows Users: get the free Borland compiler, Visual-C or MINGW)
Unix users will usually already have gcc installed (to check, type "gcc --version" at a command prompt).
Mac OSX users should install XCode or the command line tool subset.
Windows users will have to either download the free Borland 5.5 command-line tools or the Visual-C compiler or MINGW64 and install either (or all of them) at the default location.
For bcc, this is "c:\borland\bcc55". Make sure that bcc32 is found along your path by typing "bcc32" into a command window.
Also notice, that there have to be two configuration files in the bin directory: "C:\Borland\bcc55\Bin\bcc32.cfg" containing 2 lines:
```
    -I"c:\Borland\Bcc55\include"
    -L"c:\Borland\Bcc55\lib"
```
and "C:\Borland\bcc55\Bin\ilink32.cfg" containing:
```
    -L"c:\Borland\Bcc55\lib"
```
Without them, bcc-compilations and linkage will fail later (the bcc-installer does not create those files!).
For MINGW, it is best to install it at its standard location or "C:\MINGW64".

Check the Prerequisites again

Sorry to bother you again, just to make sure:

Unix Users:

Open a terminal window (xterm), and type both "cvs" and "gcc --version". There should be reasonable responses for both (aka: not "command not found").

MSDos Users:

Borland-C users should open a command window, and try both "cvs" and "bcc32" or "gcc". There should be reasonable responses for both.
In case you use Visual-C, make sure that your shell environment includes the Visual-C path (VSINSTALLDIR). In a command window, type "echo %VSINSTALLDIR%". If that value is not set, look for a batch file named "%ProgramFiles%\Microsoft Visual Studio xx.0"\VC\bin\vcvars32.bat", and execute it (xx is one of "9.0", "10.0", "11.0" etc.). If required, add a call to that batch file to your "autoexec.bat".

Sorry again, but now we are sure (too many people wrote emails in the past).

Connecting ST/X to CVS

If you don't know anything about CVS, you should download an introduction from the internet and learn about CVSRoot, modules and pserver settings.
Or else, ask a friend.

Back in Smalltalk, open the "System"-"Settings" dialog in the launcher and navigate to the "Source Code Management"-settings.

Enable Source Code Management
Turn on the "Use Local Source (suppress checkout)" checkbox
Make CVS the "Default Repository Type"
Navigate to the CVS sub-page (expand the SCM node in the settings tree)
Enable "Show CVS in Browser Menus"
specify your own repository-path in the "CVSRoot-default" field
specify ":pserver:cvs@cvs.smalltalk-x.de:/cvs/stx" as CVSRoot-per-module for the "stx"-module.
Apply the changes.

Let me explain, what that setting means:
defining exept's cvs-pserver for the "stx" module means that the source for any class under the "stx" project tree should be fetched from the exept sourceCode server. However, the "Use Local Source" flag tells it to look for a local file under the stx-tree first. That means, that for all existing classes, the pserver will never be asked, because the sources are part of the distribution and you should have them on your system.

The other setting (your own cvs repository as default) means that for all other classes, your local cvs server should be consultet.

Checking your Setup

To check if CVS access to the public repository from within ST/X works correctly, open a system browser and navigate to some standard class (for example, "Boolean") and select the class-list's "Repository"-"Revision Log" (German: "Info zu Versionen") menu item. After some delay, the browser should show the release information from exept's CVS server. You can also try the "Compare against Version in Repository" menu function, to see what has been changed relative to an older version of the Boolean class.

Don't forget to check the "Use Local Source (suppress checkout)" flag in the CVS settings dialog. If you do forget it, your browser will access the exept CVS repository whenever it needs to show the source of a class or method. Although the fetched files will be cached (so the slow cvs-access is usually only performce once), but anyway this can be quite slow and annoying for quite some time, and is actually totally useless, because all files are already on your machine.

However, you should never ever modify those source files, if that "use local source"-flag is checked. If you do, the browser will show garbage, as it trusts the file to contain the method sources at exactly the position which has been compiled into the binary. That is: the binary only contains the file-offset position of the source from which it was compiled. Setting the "use local source"-flag tells the source code mangager, that it shall use those files and NOT ask the CVS repository. If you ever see garbage source code in the browser (after you accidentically modified your seources), uncheck that flag.

Making a Project

Specifying the Project's Hierarchy

Back in Smalltalk, open a SystemBrowser and switch the view-mode to "Project" in the main menu. You should now see a project-hierarchy on the left, instead of the classical category-view.

Right-click in the project-list, and select the "New..."-menu item.

Enter a reasonable package-ID for your own project (in the documentation you will also occasionally read "project-ID" - which is the same). A package-ID consists of two parts, separated by a colon: the module name and a repository path. The module component before the colon, MUST be the same as the name of your CVS-module. The stuff after the colon will be used as the directory path within the repository. As a rule of thumb, use package-IDs of the form

myOwnTopID : projectName / componentName (no spaces in-between)

Notice that for deployed packages, every class and extension method with the same packageID will end up being compiled into the same dll. So if you have debug- and test-classes (unit tests), you'd better put them into a sub-package, such as: "myOwnTopID:projectName/componentName/test".

A concrete example would be:

theBiggerBugLTD:salesApp/startup
theBiggerBugLTD:salesApp/startup/tests
theBiggerBugLTD:salesApp/gui
theBiggerBugLTD:salesApp/gui/tests
theBiggerBugLTD:salesApp/database/
theBiggerBugLTD:salesApp/database/support

Just to give you a rough idea. Use common sense and your experience.

Move Classes into the Hierarchy

Next, all of your code should be moved to the appropriate place in the project/package hierarchy. This can be done in the System Browser either via drag & drop (by moving a class or group of classes over to the package), or by selecting the class(es) and applying the class-list menu function "Move"-"To Package...".

If your application requires extension methods (that is: extensions to other classes), these must be assigned to the corresponding package as well. For example, if you have added a method for the String class, which is required by your application, move that to the appropriate package as well (there is a "Move"-"To Package..." also found in the browser's method-list menu).

Don't forget the above step and don't try the stx project. If you do, the checkin operation below will try to check your classes into our exept repository. That will certainly fail, because what you reach there is a passive read-only copy of our real repository. Beside being read/only, it will also be overwritten when the next copy is made - typically the next night.

Adding a Project Definition

Next, we need to update or create a so-called "Project Definitions". These are classes which specify the contents and attributes of a project, and also how they are to be processed during the build. As a class, each project definition is also part of the package and is also compiled into the dll. So all the information is again automatically included and present, when the generated dll is eventually loaded into another Smalltalk.

If you created the project as described above, you should already see those project definitons in the browser's project-tree. If not, it is now time to do it.

Then, have a look at the code as present so far (it is all found on the class-protocol side).

Some of these can be regenerated via class-lists menu items "Generate"-"Project Definition" and "Generate"-"Update Project Contents Definition" and also "Generate"-"Regenerate Project Contents Definition". (They differ on how they deal with existing code, and which definitons are regenerated. For now, only use the "Update" function, and edit the rest by hand.

Notice that the generated prerequisite list only includes packages of classes which are seen by a static code analysis - if you construct class names dynamically, you should add the names of the corresponding packages manually to the list. If you update the list via the generator later, only new entries will be added. If you "regenerate", you have to repeat your additions.
If the prerequisite generator adds packages for which you are absolutely sure that they are not needed (for example: testcases), add a method named "excludedFromPreRequisites" and list those packages there.

If in doubt, use the browser and look at existing project-description classes as a guide - they are pretty easy to understand.

Library Descriptions vs. Application Descriptions

There are two types of project descriptions. One is for a library and the result of the build will be a dll. This will contain classes and extension methods (pretty much like "libbasic", "libtool", etc.).
The other type is for applications, and the build will generate an installable executable (.exe file).

We usually define applications as a sub-project named "application", and define all of the libraries as prerequisites. You are not forced to do it like that - you can also put all of your classes into the application package, and not use libraries at all. Or do a mix of both.
In any case, you will need a special startup class - that is the class which will play the role of the "main" function in a classic program. That's where the whole show starts later. Two major things must be specified: startup-className and startup-selector.

Checking into the Source Repository

Next, check in all of your classes and the project definitions into the source code repository. There are multiple ways to do this: by selecting the project and the project-lists popup menu, or by selecting individual classes, and the class-list popup menu. If you use the class-list, more work is to be done, to make sure that the extensions are also checked in (there is another item in the class-lists repository menu, called "Checkin Extensions for...").

Generating Build Support Files

In addition to the classes, you want ST/X to generate the build-support files. These consist of Makefiles for both windows and linux systems, additional resource files for the windows build, and batch scripts to start the build.

To have those files generated and also checked into the repository, select the "CheckIn Build-Support Files" from the project-lists menu (with the project selected, of course).

Checking Out

Now, it's time to open a terminal/console window (xterm or command-window), move to your ST/X top installation directory (the one above the "stx"-directory), and check out the project into your own project top.
Initially, you will need a "cvs co" command, to get the tree (checkout).
Later, a "cvs upd -d" will do, and only fetch the deltas (update).

After the checkout or update, you should see the following directory hierarchy:

   stxXXX (where XXX is the ST/X release; currently 542)
      theBiggerBugLTD
	 salesApp
	    startup
	    gui
	    ...
      stx
	 ...
	 libbasic

of course, the directory-names in the above example depend on how you named your projects in the above "Specifying the Project's Hierarchy" step.

If you look at those directories in a filebrowser, explorer or K-Filelist, you should see all of your classes as ".st" files, makefiles, a resource file for windows-building, and a "bmake.bat" driver file. All of them have been generated and checked in by the "Generating Build Support Files" step above.

Building

That is very easy:
In a command window, enter that directory, and type:

make  (unix/linux systems)

bmake  (msdos systems with borland compiler)

vcmake  (msdos systems with visual-C compiler)

That's it; the result should be an executable. For Win32 systems, if you have the nullsoft-install-system on your machine, a self-extracting install-exe is also created, which is ready for deployment. For Linux, an RPM packager is being developed and may be included in a future version (for now, simply tar/zip the build-directory, and unpack it on the target machine).

Automatic Building

Using automatic build tools like jenkins (hudson), you'd have to setup a CVS project, which checks out your module into a sibling folder of the stx tree (i.e. install or copy the stx tree on the jenkins build machine. Then, for a Unix build, enter the shell script:

    cd <yourTop>/<yourModule>/<yourDirectory>
    make

or, for a Windows build:

    cd <yourTop>\<yourModule>\<yourDirectory>
    bmake

with stx installed under "<yourTop>/stx".

Concrete Examples

A concrete GUI demo is found in:

clients/Demos/foxCalcApplication

to see how an application definition and a startup-class for standalone startup looks, load it and browse the code.

Continue in "More Smalltalk".

<cg at exept.de>

Doc $Revision: 1.16 $ $Date: 2021/03/13 18:24:49 $