72 

    72 "

    73 "/    Packager - A Standalone-Executable Builder and Packager

    73   Packager - A Standalone-Executable Builder and Packager

    74 "/    This assistant-application allows for standalone applications to be built very easily. It will generate all required classes, files, start the compilation process, generate a self-installable executable with a few mouse clicks. A simple demo application like the famous "Hello World" can be generated in a few minutes.

    74 

    75 "/    Prerequisites

    75     This assistant-application allows for standalone applications to be built very easily. 

    76 "/    Windows Users:

    76     It will generate all required classes, files, start the compilation process, 

    77 "/    Please install either the "Borland Free Commandline Compiler Tools (bcc32)" or the "Microsoft Visual-C++" package (also free). In addition, the "NullSoft NSIS-Installer Package" is required.

    77     generate a self-installable executable with a few mouse clicks. 

    78 "/

    78 

    79 "/    Due to limitations and bugs in the Visual-C++ compiler (limit on the size of string-constants), some Smalltalk code is still not compilable (classes which contain image-resource methods for big images). Although microsoft is doing their best (a relative measure) to make things better (they increase the string-limit with every new release), they still seem to be undable to figure out how ti use malloc for string-data). We are patiently waiting for a real fix and still using bcc in the meanwhile. Therefore, we still recommend using the borland compiler suite. Please install it at its standard location ("C:\Borland") as our makefiles might still contain hard-coded pathes (yes, we are ashamed about this).

    79     A simple demo application like the famous 'Hello World' can be generated in a few minutes.

    80 "/    Unix Users:

    80 

    81 "/    You should already have the gcc compile suite (including all required header files) installed and ready to use. For a lack of time on our side, there is currently no self-installer support for Unix. The packager will generate a zipped tar file, which must be deployed and unpacked for use. This may change in the near future.

    81   Prerequisites

    82 "/    Packages, Projects, PackageIDs and ProjectDefinitions

    82 

    83 "/    Smalltalk basically uses two objects for packaging:

    83     * Windows Users:

    84 "/

    84     Please install either the 'Borland Free Commandline Compiler Tools (bcc32)' 

    85 "/        * PackageIDs (also called ProjectID's occasionally)

    85     or the 'Microsoft Visual-C++' package (also free). 

    86 "/        * ProjectDefinitions 

    86      In addition, the 'NullSoft NSIS-Installer Package' is required.

    87 "/

    87 

    88 "/    Older ST/X versions used instances of a Project class - this is now obsolete and removed from the system (although there are still some minor uses of it, which might remain there for backward compatibility for some time, as some customers have built their own packaging scheme around it).

    88     Due to limitations and bugs in the Visual-C++ compiler (limit on the size of 

    89 "/

    89     string-constants), some Smalltalk code is still not compilable 

    90 "/    PackageIDs

    90     (currently, this affects classes which contain image-resource methods for big images). 

    91 "/    These are simple symbols and are attached to classes and methods. If a method has a packageID different from its class, it is called an extension method.

    91     Although microsoft is doing their best (a relative measure) to make things better 

    92 "/    PackageIDs must have a certain fixed format: they always contain exactly two parts, which are separated by a colon character: the module and the directory part. The module is used as main-selector on where and how the source code repository is accessed. The directory is a path below that repository. If checked out into the local filesystem, the module defines the top-level directory. Thus, if a packageID is "stx:libbasic", the corresponding sources will be found in the repository associated to the "stx" module, under the directory "libbasic". In the local file system, it will be found under "stx/libbasic". As another example, if the packageID is "exept:expecco/plugins/foo", the repository is whichever is associated with the "exept" module, and the subdirectory is "expecco/plugins/foo". The local path to the sourcefiles would be "exept/expecco/plugins/foo".

    92     (they increase the string-limit with every new release), they still seem to be unable 

    93 "/    Please notice that it does make sense to associate different repositories to different modules: for example, you could setup the sourceCodeManager to use CVS access to the exept repository for everything under the "stx" module, and at the same time, use a local SVN repository for everything under the "myCompany" module.

    93     to figure out how ti use malloc for string-data). 

    94 "/    ProjectDefinitions

    94     We are patiently waiting for a real fix and still using bcc in the meanwhile. 

    95 "/    These describe the contents of a project, such as the classes to include, the set of extension methods, any additional compilation information. ProjectDefinitions come in 3 flavours:

    95     Therefore, we recommend using the borland compiler suite. 

    96 "/

    96     Please install it at its standard location ('C:\Borland') as our makefiles might 

    97 "/        * GUI Application Definition

    97     still contain hard-coded pathes (yes, we are ashamed about this).

    98 "/        * non-GUI Application Definition

    98 

    99 "/        * ClassLibrary Definition 

    99     * Unix Users:

   100 "/

   100     You should already have the gcc compile suite (including all required header files) 

   101 "/    ProjectDefinitions are stored and managed as class-instances, located as subclasses of one of ApplicationDefinition or LibraryDefinition. As classes, they are themself managed, compiled and packaged as part of the project (and also have the same PackageID as their components). They are also treated like any other class w.r.t. source code management.

   101     installed and ready to use. For a lack of time on our side, there is currently no 

   102 "/    Packaging

   102     self-installer support for Unix. The packager will generate a zipped tar file, 

   103 "/    All classes and extension methods belonging to a single package are supposed to be loaded (and possibly unloaded) together. They are also usually deployed inside a single dynamic link library ("dll", for short). In the Unix world, these are called "shared object" or "so". Finally, they are stored in a common directory both on the local file system and in a source code repository (CVS, SVN, etc.).

   103     which must be deployed and unpacked for use. This may change in the near future.

   104 "/    Structure of a Project

   104 

   105 "/    The artefacts as manipulated by the packager are:

   105   Packages, Projects, PackageIDs and ProjectDefinitions

   106 "/

   106 

   107 "/        * the ProjectDefinition class

   107     Smalltalk basically uses two objects for packaging:

   108 "/          This defines the type of application (GUI / non-GUI), its contents (i.e. the set of classes to be included in the binary itself and the set of library-dll's to be included in the deployed package), and some other metadata, such as icon, title etc.

   108 

   109 "/

   109         * PackageIDs (also called ProjectID's occasionally)

   110 "/        * the ApplicationModel class

   110         * ProjectDefinitions 

   111 "/          This defines the GUI, and is typically created using the UI-Painter.

   111 

   112 "/

   112     Older ST/X versions used instances of a Project class - this is now obsolete and 

   113 "/        * the Startup class

   113     removed from the system (although there are still some minor uses of it, 

   114 "/          This is the first class which gets control when the executable is started; it can analyze the command line arguments, read patches or updates, start background ptocesses, and will eventually open the applications GUI. 

   114     which might remain there for backward compatibility for some time, as some customers 

   115 "/

   115     have built their own packaging scheme around it).

   116 "/    Build Procedure

   116 

   117 "/    All of the three components above can be generated by the packager to provide an initial framework for further work.

   117   PackageIDs

   118 "/

   118 

   119 "/    After the definition of those classes, all required files are stored in a temporary build directory. This means that the above classes are filed out, and make- and other support files are generated.

   119     These are simple symbols and are attached to classes and methods. If a method has 

   120 "/

   120     a packageID different from its class, it is called an extension method.

   121 "/    Finally, the actual build process is started. This requires an external C-compiler. Under windows, both Borland-C (free download available via the internet) and Microsoft's Visual-C++ (also available for free) can be used.

   121     PackageIDs must have a certain fixed format: they always contain exactly two parts, 

   122 "/

   122     which are separated by a colon character: the module and the directory part. 

   123 "/    A self-installing executable is built using the NullSoft NSIS package. This is also required to be installed before the packager is started.

   123     The module is used as main-selector on where and how the source code repository is 

   124 "/

   124     accessed. The directory is a path below that repository. If checked out into the local 

   125 "/    After the build, all required files are packaged in a single install-file. This is called "MyApplicationSetup.exe" and found in the project-specific subdirectory of the build directory. For deployment, this single file has to be delivered to a customer and executed there.

   125     filesystem, the module defines the top-level directory. Thus, if a packageID is 

   126 "/

   126     'stx:libbasic', the corresponding sources will be found in the repository associated 

   127 "/    Summary: It has NEVER been easier to create a GUI application. 

   127     to the 'stx' module, under the directory 'libbasic'. 

   128     In the local file system, it will be found under 'stx/libbasic'. 

   129     As another example, if the packageID is 'exept:expecco/plugins/foo', 

   130     the repository is whichever is associated with the 'exept' module, and the subdirectory 

   131     is 'expecco/plugins/foo'. The local path to the sourcefiles would be 

   132     'exept/expecco/plugins/foo'.

   133 

   134     Please notice that it does make sense to associate different repositories to different 

   135     modules: for example, you could setup the sourceCodeManager to use CVS access to the 

   136     exept repository for everything under the 'stx' module, 

   137     and at the same time, use a local SVN repository for everything under the 'myCompany' 

   138     module.

   139 

   140   ProjectDefinitions

   141 

   142     These describe the contents of a project, such as the classes to include, 

   143     the set of extension methods, any additional compilation information. 

   144     ProjectDefinitions come in 3 flavours:

   145 

   146         * GUI Application Definition

   147         * non-GUI Application Definition

   148         * ClassLibrary Definition 

   149 

   150     ProjectDefinitions are stored and managed as class-instances, located as subclasses 

   151     of one of ApplicationDefinition or LibraryDefinition. 

   152     As classes, they are themself managed, compiled and packaged as part of the project 

   153     (and also have the same PackageID as their components). 

   154     They are also treated like any other class w.r.t. source code management.

   155 

   156   Packaging

   157 

   158     All classes and extension methods belonging to a single package are supposed to be 

   159     loaded (and possibly unloaded) together. They are also usually deployed inside a single 

   160     dynamic link library ('dll', for short). In the Unix world, these are called 

   161     'shared object' or 'so'. 

   162     Finally, they are stored in a common directory both on the local file system and in a 

   163     source code repository (CVS, SVN, etc.).

   164 

   165   Structure of a Project

   166 

   167     The artefacts as manipulated by the packager are:

   168 

   169         * the ProjectDefinition class

   170           This defines the type of application (GUI / non-GUI), 

   171           its contents (i.e. the set of classes to be included in the binary itself and 

   172           the set of library-dll's to be included in the deployed package), 

   173           and some other metadata, such as icon, title etc.

   174 

   175         * the ApplicationModel class

   176           This defines the GUI, and is typically created using the UI-Painter.

   177 

   178         * the Startup class

   179           This is the first class which gets control when the executable is started; 

   180           it can analyze the command line arguments, read patches or updates, 

   181           start background ptocesses, and will eventually open the applications GUI. 

   182 

   183   Build Procedure

   184 

   185     All of the three components above can be generated by the packager to provide an 

   186     initial framework for further work.

   187 

   188     After the definition of those classes, all required files are stored in a temporary 

   189     build directory. This means that the above classes are filed out, 

   190     and make- and other support files are generated.

   191 

   192     Finally, the actual build process is started. This requires an external C-compiler. 

   193     Under windows, both Borland-C (free download available via the internet) and Microsoft's 

   194     Visual-C++ (also available for free) can be used (the later with some limitations as explained above).

   195 

   196     A self-installing executable is built using the NullSoft NSIS package. 

   197     This is also required to be installed before the packager is started.

   198 

   199     After the build, all required files are packaged in a single install-file. 

   200     This is called 'MyApplicationSetup.exe' and found in the project-specific subdirectory 

   201     of the build directory. For deployment, this single file has to be delivered to a customer 

   202     and executed there.

   203 

   204     Summary: It has NEVER been easier to create a GUI application with Smalltalk. 

   205 "

   145             infoText: 'Choose an existing project definition or create a new one.

   223             infoText: 'Choose an existing project definition or create a new one. These are subclasses of <I>ProjectDefinition</I> and define the type and contents of a project.'

   146                        These are subclasses of <I>ProjectDefinition</I> and define the

   147                        type and contents of a project.'

   156             infoText: 'Choose an existing application or create a new one.

   232             infoText: 'Choose an existing application or create a new one. These are subclasses of <I>ApplicationModel</I> and define the GUI and control flow inside the application. Can also be left blank if the startup class does it all (stx build).'

   157                        These are subclasses of <I>ApplicationModel</I> and define

   158                        the GUI and control flow inside the application.

   159                        Can also be left blank if the startup class does it all (stx build).'

   168             infoText: 'Choose an existing startup-class or create a new one.

   241             infoText: 'Choose an existing startup-class or create a new one. These are subclasses of <I>StandaloneStartup</I> and start the application. Command line arguments can be interpreted there.'

   169                        These are subclasses of <I>StandaloneStartup</I> and 

   170                        start the application. Command line arguments can be

   171                        interpreted there.'

   179             infoText: 'Define which (other) classes are to be included.

   249             infoText: 'Define which (other) classes are to be included. Press "<I>Scan</I>" to include all classes of the package; browse to edit the contents manually.'

   180                        Press "<I>Scan</I>" to include all classes of the package;

   181                        browse to edit the contents manually.'

   195             infoText: 'Define where the build-process is to be performed.

   263             infoText: 'Define where the build-process is to be performed. All generated files are created below that directory. After deployment, the build directory is no longer needed (but you can keep it for a faster compile the next time).'

   196                        All generated files are created below that directory.

   197                        After deployment, the build directory is no longer needed

   198                        (but you can keep it for a faster compile the next time).'

   199 

   209             infoText: 'Start the build-process. This will run make/bcc to compile

   273             infoText: 'Start the build-process. This will run make/bcc to compile all required classes and nsis to generate a self-installable executable. You must have the borland-cc and NullSoft NSIS packages installed for this to work.'

   210                        all required classes and nsis to generate a self-installable

   211                        executable. You must have the borland-cc and NullSoft NSIS

   212                        packages installed for this to work.'

   219             infoText: 'Find the installer to be deployed (or test-run the binary).

   280             infoText: 'Find the installer to be deployed (or test-run the binary). You can open a WindowsExplorer there to copy the files for deployment. After that, the build directory is no longer needed (but you can keep it for a faster compile the next time).'

   220                        You can open a WindowsExplorer there to copy the files for

   221                        deployment. After that, the build directory is no longer needed

   222                        (but you can keep it for a faster compile the next time).'