Installing Af-Arch client side on Windows

Index

Introduction

This will help you to build Af-Arch client side on windows platforms. The framework have been tested under Microsoft Windows XP. It shouldn't be a problem to get Af-Arch running on an diferent windows platform.

The only exception is Af-Archf# component. It is not available on Windows 9X platforms. This is because there are poorly support to UTF-8 on that platforms and .NET runtimes makes an intesive use.

Af-Arch client side components are:

libraries:
tools:
- aspl-clm
- af-gen

Source code and Stables releases

You can use the latest stable release already package and tested allways found at:

http://www.sf.net/projects/aspl-fact

However, you can try with the lastest svn version located at:

https://dolphin.aspl.es/svn/publico/af-arch

Requierements and downloads

You need to have the following software installed in order to be able to compile and install the framework. Not all these software dependencies are required. Those requirement not meet will be considered as a selection to not build the component.

The platform used to compile the Af-Arch is MinGw. You can download it from http://www.mingw.org.

Download the MinGW package (this package contains the gcc, binutils and other tools to compile software). The package version I've used was MinGW-4.0.4.exe however any MinGW next release should do.

Then download the Msys enviroment which is a package which contains an minimal posix environment. The package I've used was Msys-1.0.10.exe.

It is not requiered but I have also download from MinGW site the bash package.

Then you can download libglib 2.0 (at least 2.6), libiconv and gettext precompiled packages for windows from: http://www.gimp.org/~tml/gimp/win32/.

The link may change. Check out the win32 section from http://www.gtk.org in case of problems. The libglib 2.0 requiered version is at least 2.6.0.

Do not use the precompiled packages for libxml 2.0 that can be found on the previous site. This package was compiled by Igor Zlatkovic (that can be found at http://www.zlatkovic.com/projects/libxml/binaries.html) have a bug which makes break the Af-Arch. Of course, this may change on the future.

Instead try the libxml 2.0 precompiled from http://gnuwin32.sf.net. You can also find precompiled packages for libreadline at this site.

To get the Mono runtime download the Mono package for win32 at http://www.mono-project.com. The version I used was 1.1.7 release.

To be able to build af-gen tool, you have to download the bison package

Some notes before starting

Before starting to install keep in mind the following facts which will help you to avoid common problems:

Windows platform is case sensitive which means that files and directory names are interpretected as they were all lower case letter. This will cause you problems because the Msys environment is not case sensitive.
```
    Recomendation: use lower case letter for the installation
    directories.
```
Cygwin environment and MinGW are somewhat incompatible. Both platform creates native executables for the Windows platforms but the first one links every executable to cygwin1.dll and the second to the microsoft runtime dll msvcrt.dll or kernel32.dll.
If you have installed the Cygwin enviroment make sure you don't reach libraries, binaries and tools throught your PATH variable while compiling components with MinGw environment.
If a binary is compiled against a library which was compiled with cygwn and then you link your executable compiled with MinGw you will get really extrange behaviours.
Use the following procedure to check this condition. To check if a dll or executable is built against the cygwin1.dll you'll get the following output after executing:
```
    (09:21:58-Fri Jun 03)
    [acinom@TITAN src]$ objdump.exe -p /c/cygwin/bin/cp.exe |grep \.dll
        DLL Name: KERNEL32.dll
        DLL Name: cygwin1.dll
        164d8     735  dll_crt0__FP11per_process
        DLL Name: cygintl-2.dll       
```
If you check the same but for a MinGw executable you'll get:
```
    (09:22:02-Fri Jun 03)
    [acinom@TITAN src]$ objdump.exe -p /bin/cp.exe |grep \.dll
        DLL Name: KERNEL32.dll
        DLL Name: msys-1.0.dll
        1535c     643  dll_crt0__FP11per_process
```
At this moment the Mono project doesn't compile its products under the Cygwin enviroment. This makes imposible to use Cygwin enviroment to produce binaries to be used inside or from the Mono enviroment.
In the past Af-Arch project use to use the Cygwin enviroment to develop windows applications but the experience have showed us that is better to use other approaches such as: MinGw or using other propieraty product which generate native binaries.
In fact, the Cygwin enviroment is really easy to use and develop under it but is a terrible chunk of pain to be able to produce package installation for other stations which will be used by normal users and therefore they don't need the Cygwin enviroment.
Conclusion: the Cygwin enviroment makes you to get hard linked to it.

Af-Arch# developing dependencies install steps

If you are planing to develop Mono enabled Af-Arch applications, just install it without installing the LibGlib, LibIconv, GetText and Libxml. They are bundled with the Mono installation across the developer files.

In case you are going to develop a C Af-Arch aplication install that components in the order you consider.

Compiling and installing downloaded tools

Start to install the MinGw package on the directory you choose. Keep in mind this directory will be used to build the Af-Arch project. I selected to install it on c:/mingw.

Then install the Msys in a separated directory so you can track which package provide each library, tool, file, etc. The Msys installer will ask you for the MinGW directory to apply some normalization operations between both packages. I selected to install it on c:/msys

Then install the additional libraries inside the MinGW environment but in a separated directory. I chose to install them on c:/libraries.

Now, edit the Makefile.win under the top source dir unsing the previous value. As an example, and using previous values:

     BASE_DIR=c:/libraries

Compiling and installing with Mono

Because the Af-Arch# is a .NET binding based on P/Invoke you will need the Af-Arch libraries to be compiled against the libraries the Mono installer comes with. If you compile the Af-Arch libraries against other (those you may have download from the previous sites) you will get extrange hangups.

While compiling the Ar-Arch# module you have to provide the Mono root installation directory:

   MONO_DIR= C:/ARCHIV~1/MONO-1~1.10

NOTE: It is prefered to use the short window path, that is, C:/ARCHIV~1/MONO-1~1.10 than the long name format.

Additionally, you can configure BASE_DIR using the same value as MONO_DIR environment var. This is because the libraries needed by Af-Arch are also provided by the Mono installation.

You have to modify your PATH environment variable to include a reference to the bin directory of the following items:

   - c:\msys\1.0\bin
   - c:\Program\ Files/Mono-1.1.7/bin

Modify your environment variable as follows:

   Path = ...;c:\msys\1.0\bin;c:\Program\ Files/Mono-1.1.7/bin

On windows XP this is done at the "Advanced Preferences" at "My PC" properties.

NOTE: Some Mono installation do not include developer files for Zlib and Libxml. Releases know to be broken are: 1.1.8-1.1.10. Drop us an email at the mailling list to get access to missing files.

Compiling the sources

NOTE: Do not use the MinGW shell to type the following command while developing with Mono. It is prefered to run the following using the Windows command line tool: cmd.

Now type:

 make -f Makefile.win

Once all produce are build, you can type:

     make -f Makefile.win install

This will install all software components under the directory INSTALL_DIR. If you didn't change that variable the result will be installed under ./win32-build. Inside that directory you will find the following content:

bin Tools, dll and tests
Under this directory you find dlls needed by Af-Arch applications. The directory content will be needed to be install under production enviroments.

lib Import libraries.
While developing with dll you may need the import libraries to link your programs with the Af-Arch system.
This import libraries may be useful. In the past the import library was required to be able to link against a particular dll. Currently gcc team have produce a gcc which is able to link your program directly only using the dll files.
This files are not requiered on production enviroments.

include Include headers to develop with the Af-Arch.
You'll need this to develop new Af-Arch applications. Files on this directory are header includes. They are not nedeed in production environments.

sharp Assemblies to be installed inside other system.
You'll need this to develop new Af-Arch .NET applications using Mono, Portable.NET or the Microsoft .NET Framework.
This assemblies should be installed by using the gacutil tool while porting the result to other boxes.

Af-Gen support files for win32 (or how compile af-gen products)

Inside the af-gen install directory you will find a directory called data. On this directory you will find some files that may be usefull to build Af-Arch libraries genereted by the af-gen tool. Files are:

Makefile.win.c: makefile to compile the C STUB connector on windows using MinGw installation. This component will have the following form: libafdal-yourserver.
Makefile.win.sharp: makefile to compile the C# STUB connector on windows using Mono environment. This will have the following form: libafdal-youserver-sharp.

Compiling libafdal-your-server (libafdal c interface) on windows

Before doing nothing you need to have already installed the Af-Arch on your platform. See this section.

Once you have generated the source code for the library using af-gen tool you may use the Makefile.win.c to get that library compiled.

Copy Makefile.win.c on that src directory for the library the af-gen tool have created. Rename the Makefile.win.c to Makefile. This will allow you to use make without using the modifier -f.
```
         $ cp af-gen-install-dir/data/Makefile.win.c \
                 libafdal-yourlibrary/src/Makefile
```

Now edit the file to tweak the base_dir, install_dir and dll_name make variables.

base_dir: configures the Af-Arch installation directory. This will be used to lookup include headers, import libraries and dlls.

install_dir: configures the library installation. Maybe you want to do make install.

dll_name: sets the output dll name. This name must be set carefully following the next indications:
If your library is called libafdal-your-server you have to set dll name to "afdal_your_server". Because:

If you doesn't do that you will not be able to use C# interface.

The "libafdal-" allaways is removed and translated into "afdal_"

Every "-" must be translated into "_".

The final .dll prefix is added by the compilation process.

The result of using afdal_your_server is a dll called: afdal_your_server.dll

Once finished you can type inside the src directory:

      bash:~$ make
      bash:~$ make install

Compiling libafdal-your-server-sharp (libafdal c# interface) on windows

As a reminder: you have to get the c insterface also installed. The libafdal c# interface is a binding for the c interface so the implementation keeps the same under one language which allows to easily create binding for other languages.

As the previous section, you have to use the Makefile.win.sharp file which can be found inside the data directory of the af-gen installation.

Copy the Makefile.win.sharp file inside the src directory of the csharp generated files.

         $ cp af-gen-install-dir/data/Makefile.win.sharp \
                 libafdal-yourlibrary-sharp/src/Makefile

Now edit the makefile to set the following variables:

mono_dir: the Mono installation directory.

install_dir: the directory where the assembly will be installed. Althought the Makefile.win.sharp already install the assembly into the GAC, it is also installed under the install_dir so application can compile against it.

assembly_name: this variable will control the assembly name output. It should named as follow: afdal-yourserver-sharp.

Now type:

      bash:~$ make
      bash:~$ make install

bin	Tools, dll and tests Under this directory you find dlls needed by Af-Arch applications. The directory content will be needed to be install under production enviroments.
lib	Import libraries. While developing with dll you may need the import libraries to link your programs with the Af-Arch system. This import libraries may be useful. In the past the import library was required to be able to link against a particular dll. Currently gcc team have produce a gcc which is able to link your program directly only using the dll files. This files are not requiered on production enviroments.
include	Include headers to develop with the Af-Arch. You'll need this to develop new Af-Arch applications. Files on this directory are header includes. They are not nedeed in production environments.
sharp	Assemblies to be installed inside other system. You'll need this to develop new Af-Arch .NET applications using Mono, Portable.NET or the Microsoft .NET Framework. This assemblies should be installed by using the gacutil tool while porting the result to other boxes.

mono_dir:	the Mono installation directory.
install_dir:	the directory where the assembly will be installed. Althought the Makefile.win.sharp already install the assembly into the GAC, it is also installed under the install_dir so application can compile against it.
assembly_name:	this variable will control the assembly name output. It should named as follow: afdal-yourserver-sharp.