[prev] [up] [next]

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.
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

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:


Open a command window, and type both "cvs" and "bcc32". There should be reasonable responses for both.
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 a "System"-"Settings" dialog from the launcher and navigate to the SourceCode management-settings.

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 means that for all other classes, your local cvs server should be consultet.

To check if CVS access works correctly, navigate to some ST/X standard class (for example, Boolean) and select the classLists "Repository"-"Revision Log" (German: "Info zu Versionen") menu item. After some delay, the browser should show the release information from exept's CVS server.

Don't forget to check the "use local source (suppress checkout)" flag. If you do forget it, your browser will try to access our (exept's) CVS repository once for every class, which will be very slow. The fetched files will be cached, but anyway this will be very slow for quite some time, and is totally useless, because all files are already on your machine.

Making a Project

Specifying the Project's Hierarchy

Back in Smalltalk, open a SystemBrowser, switch the view-mode to "project" via 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 rpoject. 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 CVS repository. As a rule of thumb, use projectIDs of the form

myOwnTopID : projectName / componentName (no spaces inbetween)
Notice that for the deployed package, every class and extension method with the same projectID 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 you code should be moved to the appropriate place in the project hierarchy. This can be done either via drag & drop (by moving a class or group of classes over to the project), or via by selecting the class(es) and applying the class-list menu function "Move"-"To Project".

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 requiered by your application, move that to the approppriate project as well (there is a "Move"-"To Project" 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 so-called "Project Definitions". These are classes which specify the pieces which are part 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 it describes 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 browsers 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 the class-lists "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 nly includes classes which are seen by a static code analysis - if you construct class names dynamically, you should add the names of those classes manually to the list. (if you update the list via the generator later, only new classes will be added.)
If the preRequisite generator adds classes for which you are sure that they are not needed (for example: test cases), add a method named "excludedFromPreRequisites" and list those packages there.

If in doubt, use the source and take the existing project-descriptoin classes as a guide.

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.

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 classList popup menu. If you use the classList, more work is to be done, to make sure that the extensions are also checked in (there is another item in the classLists 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 projectLists 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)
or
bmake  (msdos systems with borland compiler)
or
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 deplyoment. 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).

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".

[stx-logo]
Copyright © Claus Gittinger Development & Consulting
Copyright © eXept Software AG

<cg@exept.de>

Doc $Revision: 1.8 $ $Date: 2009/11/03 19:16:49 $