Developing and Deploying an Application in Smalltalk/X

...using Smalltalk/X jv-branch

This tutorial shows a (nearly) complete development cycle for a hypothetical application helloworld_0. Not the coolest name, I know. You should choose better for your app!

Step 1: Preparing Development Environment

First you need to make sure you're able to compile Smalltalk/X jv-branch as such.

Make sure you have installed a C compiler tool-chain and version control tools as they are essential for compiling Smalltalk/X jv-branch.

In order to build the complete environment you should follow the steps described in the Building Smalltalk/X jv-branch section.

Throughout this tutorial the demo0 directory is used for all the project files.

Let's start with checking out essential ​build scripts that will fetch core source and set up a working Smalltalk/X jv-branch build environment:

hg clone https://swing.fit.cvut.cz/hg/stx-goodies-builder-rake demo0
cd demo0
rake

This may take some time. It depends you your CPU, internet connecting, etc.

(note: Be aware that you may experience difficulties connecting to some of the sources in heavy firewall(ed) environments.)

Step 2: Creating a Repository for Application Code

Let's assume, you're starting with a greenfield project. You need to store your sources in a version control.

Smalltalk/X jv-branch comes with ​decent support for Mercurial so let's use it in this tutorial. (note: You may also use ​CVS but, believe me, you don't want to use it, especially, if far superior versioning system as Mercurial is available at your disposal.)

First, you need to decide to which (Smalltalk/X) package would code go. Let's say it should go to package named jv:demos/helloworld_0. Enter demo0 subdir and create a new repository for it:

mkdir build\jv\demos
hg init build\jv\demos\helloworld_0

To explain the details of what is happening:

• The whole jv:demos/helloworld_0 is a package name. The characters : / are just separators. (The colon character : is there due to legacy purposes CVS separates "CVS module" from "directory", in Merurial it serves no purpose).

• The directory build\jv\demos will host the initialized Mercurial (via hg init) and also during the application compilation you will see multiple files needed for the compilation.

That's it.

Step 3: Create Initial Application Code

Before we start writing the code Mercurial needs to be configured:

• Setup the path for the Mercurial+ executable

• Have a Mercurial+ as default Repository Type

• Optional: You can setup a per module versioning system - could be useful if multiple versioning systems are in play:

• To verify you have Mercurial+ setup correctly print this: AbstractSourceCodeManager managerForPackage: Smalltalk package => the result should be HGSourceCodeManager

Now it's time to write some code. Basically you need to create at least three classes:

• jv_demos_helloworld_0 - so called project definition class. This class contains a metadata about the package. Think of it as ​setup.py in Python or ​.gemspec in Ruby.
• HelloWorld0 - the main application class. This is where the real logic is.
• HelloWorld0Start - the application entry point. When the application is compiled to a standalone executable, once the Smalltalk/X VM initialize itself, it transfer control to HelloWorld0Start>>main: passing command line arguments. Think of it as of int main(int artc, char **argv) in C. In this method you may process command line arguments and eventually fire the main application - HelloWorld0>>open.

Let's do it. Launch Smalltalk/X IDE:

cd build\stx\projects\smalltalk
smalltalk -I --quick

To create a New Project (via wizard) first a switch to package view has to be done - via menu click on View ▷ Package. Next is to create a new package - via menu click on Package ▷ New...:

Using the wizard will create (almost) all the necessary code for you:

• In the first dialog, choose GUI-Application as application type and fill in a package name - jv:demos/helloworld_0 and click Create. This would create an empty "application" package.
• Next you'd be asked for an application class name. Fill in HelloWorld0. Once you click OK the wizard will create the class and generate some initial code. You may change the code later.
• Next you'd be asked for a startup class name (the suggestion will be HelloWorld0Start). Likewise, this will create an initial startup class and generate a default main: method that will open an application specified in previous step.

Although most of the code has been generated, one little tweak may be needed. When user closes main application window either by clicking to X button in title bar or picking an exit menu item, we'd like the whole application to terminate. This is not done automatically but it's easy to fix. All we need to is in method HelloWorld0>>closeDownViews call Smalltalk exitIfStandalone: 0:

Do not call plain old Smalltalk exit:0. The problem with this is that if called from IDE (for example when debugging or testing the application) it would terminate the IDE which is likely something you don't want.

Step 4: Viewing the design of the helloworld_0 application

To check the design of the application in GUI Painter you generally have these options:

a) This is a preferred way to open an spec you need. If you want the whole application alias windowSpec you can open it via browser -> clicking on Class (methods) and double click on windowSpec (found in interface specs). If you want to open menu specifications (menu specs) you can select one of the menuSpecs presented there.

Follow the steps on the picture to open the windowSpec:

To edit menu of the application:

b) An alternative way to open is to open empty instance of GUI Painter and load the GUI from there. This is done via File -> Load... . There you have to select your application HelloWorld0 and the selector you want to use windowSpec

Steps to follow for alternative opening of the application:

Step 5: Committing Code

To commit the code to Mercurial repository, simply select the package in browser and pick Package ▷ Repository ▷ CheckIn?... menu. Fill in a commit message and click Commit:

Note: A mistake in path/package pair will cause commit functionality to be suspended (the CheckIn? functionality will be grayed out)

Step 6: Reopening your application from Mercurial

In order to open your application you need to manually update your Mercurial repository.

Done via hg update:

This is done in order to make sure you have the latest source.

To load the source from Mercurial to Smalltalk/X you can type into workspace:

Smalltalk loadPackage: 'jv:demos/helloworld_0' and perform Do It operation:

In the Smalltalk/X launcher you should see:

You can then check your package in your StX browser and continue working with it and performing commits when you need it.

This is how it should look like when correctly loaded:

Step 7: Compiling Standalone Application

By standalone application we mean an executable (.exe on Windows) and bunch of libraries (.so or .dll) which can be deployed at user machine.

First we need to update a working to the latest code:

cd build\jv\demos\helloworld_0
hg up

Use hg sum that correct revision is checked out.

• To compile the application on Windows (use cmd.exe), just do (if you are in the build\jv\demos\helloworld_0 directory)

  ..\..\..\bin\setenv.bat
  cd build\jv\demos\helloworld_0
  mingwmake
  

  Note: In case the path settings using setenv.bat fails you can fix it manually by adding your \bin path in front of c:\msys2 in your path An example of such path could look like this:

...;C:\prg_sdk\smalltalkx-jv-branch-6.2.5_x86_64-win32\bin;;C:\msys64;C:\Program Files (x86)\WinAnt\bin;c:\msys64\usr\bin;C:\Program Files\Mercurial;...

• On Linux, just do

  cd build\jv\demos\helloworld_0
  make -f Makefile.init
  

If compilation succeeds, you should find helloworld_0.exe on Windows; on Linux you will find helloworld_0.

Just run it and your new application should come up:

Time for a beer!

Topics not (yet) covered

• Creating and running tests for application
• Creating installer
• Configuring Jenkins job