[ Jocelyn Ireson-Paine's Home Page | Free software | Publications ]

Installing the Gnat Ada AWS Web development framework on Windows XP

This is a guide to installing the AWS Web development framework on Windows XP. I hit a few problems when I tried it, mainly to do with getting up-to-date versions of the Unix "make" utility needed when building the system, and I thought it would be nice to save others the same bother. So this guide describes what I did. Hopefully, it will work for you too. I wrote the original of this page in 2008. In 2011, I installed a new version, which needed slightly different things done. I've described these in the section New for 2011.

The AWS mailing list

There is an AWS mailing list which you can subscribe to at http://lists.adacore.com/mailman/listinfo/aws. The archives are at http://lists.adacore.com/pipermail/aws/. Difficulties with AWS on Windows have been discussed a number of times, so if you hit problems, I recommend an exhaustive read through the archives.

Installing and testing Gnat Ada

I first installed AdaCore's free Ada, Gnat GPL. If you have already done that, please go to the section on installing and testing AWS. The instructions there will probably apply to AdaCore's commercial Ada versions too.

Installing Gnat GPL

To get Gnat GPL, I went to https://libre.adacore.com/ and set up an account via the "Create a new account" link in the right-hand top corner. You need this before you can download Gnat.

Once logged in to this, I went to the download page and selected x86-windows 2008 as my platform. (I am running XP on a Toshiba Satellite Centrino laptop.) Then I clicked on gnat-gpl-2008-pentium-mingw32msv-bin.exe, saved this to my laptop, and ran it. Doing so installed Gnat GPL. I didn't bother with the Eclipse plug-in.

Testing Gnat GPL

To test the installation, I created the following example Ada program as a text file called hello.adb. For completeness, I'll add that this was in my directory c:\test\, though the location shouldn't matter:

with ada.text_io;   -- Tell compiler to use i/o library
use  ada.text_io;   -- Use library routines w/o fully qualified names
procedure hello is
begin
    put("Hi 320");
end hello; 

I then opened a DOS command window, changed directory to c:\test\ in it, and compiled and linked the program by typing the command:

gnatmake hello.adb

Hi 320

Installing and testing AWS

Installing Cygwin

Cygwin is a Unix-style command shell that enables you to run Unix commands under Windows. (I find it useful whenever I want to compare files, because it provides the Unix diff command for doing so.) You need to install this. You also need to install the "make" utility needed to build the AWS libraries. Although you must invoke this from Cygwin, it doesn't automatically get installed when you install Cygwin: a point that seems to have tripped up a few mailing-list subscribers.

I already had Cygwin on my laptop, but I reinstalled it anyway, to avoid potential compatibility problems between an old version and Gnat. To do so, I went to http://www.cygwin.com/, clicked on the green-in-black Cygwin icon (There are two: one in the top right-hand corner, and one near the bottom of the page. Both link to the same program.), and saved the resulting file, setup.exe, to my desktop. This is the Cygwin installer.

I then ran this installer. Accepting all the defaults offered by the install wizard worked fine, except that the British mirror site in the "Choose A Download Site" window didn't work. British readers may like to know that http://ftp.uni-kl.de did work.

Testing Cygwin

Installing Cygwin places a green-on-black Cygwin icon on your desktop. Clicking on this will bring up a black-backgrounded command window, much like the Windows DOS window. This will display a dollar prompt. You can then type Unix commands into it. For example, on my laptop:

cd /cygdrive/c/test
ls

Installing the "make" utility

You can actually install "make" when you install Cygwin, but I did so separately. I did so by running the Cygwin installer that I'd saved to my desktop as above, then clicking on it. Before doing so, close any open Cygwin command windows, otherwise installing "make" will crash.

Next, proceed through the installer windows headed "Cygwin Net Release Setup Program", "Choose A Download Source", "Select Root Install Directory", "Select Local Package Directory", "Select Your Internet Connection", "Progress", "Choose A Download Site", "Progress", to the "Select Packages" window. There is a View button near the right-hand side. Clicking this gives an alphabetical list of package names: it's a wide layout, so you may need to scroll right in order to see them.

Scroll down the list until you get to "make". My window has the words "The GNU version of the 'make' utility'" to its right. To its left is an arrowed circle and the word "Skip". Clicking on this changed it to "make"'s version number: 3.81-2, for me. Then press Next, and follow the remaining steps. This should install "make".

Testing the "make" utility

Open a Cygwin command window and type:

make --version 

GNU Make 3.81
Copyright (C) 2006  Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

Note that I originally installed what turned out to be an older "make", version 3.80, 2002. This failed horribly when I tried using it to build AWS.

Downloading AWS

I downloaded the AWS source, aws-gpl-2.5.0-src.tgz from the AWS link on the AdaCore downloads page and extracted it into an empty directory. When I did this, it created a subdirectory holding the top level AWS files, including makefile and makefile.conf. For convenience, I renamed this directory to be c:\aws\. It probably doesn't matter what you call it, since the final stage of installation will copy needed files to a permanent location in Gnat's library system.

Editing the makefiles

In building AWS, the "make" utility is driven by makefile in the top-level AWS directory. You shouldn't need to edit makefile, but it tells "make" to include another, makefile.conf, which you do need to edit. So it's worth making a copy of makefile.conf which you can revert to if necessary.

You probably won't need to know how "make" works. But if you're interested, there are a number of tutorials on the Web, for example An Introduction to the UNIX Make Utility.

Edit makefile.conf so that the INSTALL variable points to the top-level directory you put Gnat in. The path has to be something that "make" running under Cygwin will understand: a Unix format path, not Windows format. On my laptop, it was the Cygwin equivalent of c:\gnat, namely /cygdrive/c/gnat. So my INSTALL line read:

INSTALL	 = /cygdrive/c/gnat

As well as setting INSTALL, I found that I had to edit another makefile, as described in my next section. I haven't had to make any other edits to makefile.conf.

Setting ADA_PROJECT_PATH

I believe that the ADA_PROJECT_PATH environment variable needs to be set before you do a "make". It should point to the lib\gnat\ subdirectory of the top-level directory you put Gnat in. That is, the directory pointed at by the INSTALL variable above.

On my laptop, the top-level directory was c:\gnat, so I set ADA_PROJECT_PATH to c:\gnat\lib\gnat. Do so using the Environment Variables tab from the Windows Control Panel.

Doing the "make"

Open a Cygwin command window, and in it, change to the top-level AWS directory. On my laptop, I did so with the command:

cd /cygdrive/c/aws

You can then try building AWS with the following three commands.

make setup
make build
make install

However, on my laptop, one of them failed, and I had to edit another makefile, then try again, as I'll now explain. After reading the AWS mailing list, I discovered that Vincent Tourvieille in this post had had the same problem. Pascal Obry's solution was to insert the line:

CC=gcc

ODIR = ../$(BDIR)/obj/win32

make setup
make build
make install

Note that if you give these commands and then decide to change the INSTALL path in makefile.conf, you must then give all three commands again.

Setting ADA_INCLUDE_PATH

I believe that, before you can compile Ada code that uses AWS, you must update the environment variable ADA_INCLUDE_PATH.

The top-level directory where I put Gnat is c:\gnat\, and I set ADA_INCLUDE_PATH to:

 
c:\gnat\include\aws;c:\gnat\include\aws\components

These two directories contain package specifications (.ads files) needed by the Ada compiler. Note that these paths are in Windows format. I had to set them using the Environment Variables tab from the Windows Control Panel. Setting them from Cygwin doesn't seem to work, even if you invoke the Ada compiler later in the same Cygwin session.

Setting PATH to refer to AWS .dll files

Before you can run Ada code that uses AWS, you have to update the PATH environment variable so it points at the .dll files supplied with AWS.

The make install command that you did earlier should have copied them to the lib\ subdirectory of the top-level directory you put Gnat in.

The top-level directory where I put Gnat is c:\gnat\, so I added this directory to my PATH:

c:\gnat\lib

I did this using the Environment Variables tab from the Windows Control Panel.

Testing AWS by running the hello_world demo built earlier

The make install that you did above should have rebuilt the demo programs that come with AWS. On my laptop, it put the resulting .exe files in

c:\aws\.build\release\relocatable\demos

The demo program source files are in the demos subdirectory of the AWS top-level directory. On my laptop, this is c:\aws\demos\.

I tested hello_world.exe by giving the command

c:\aws\.build\release\relocatable\demos\hello_world.exe

This output the following message on the DOS window:

Call me on port 8080, I will stop in 60 seconds...

It also (on my installation) caused a Windows Security Alert dialogue box to pop up, asking whether I wanted to keep blocking this program. I pressed the Unblock button on this dialogue box.

Once you have done that, you can test hello_world by connecting a Web browser to it on this address:

http://127.0.0.1:8080/

When I did so, my Web browser displayed this message:

Hello world !

Testing AWS by compiling and running your own hello_world demo

I next tried to compile and run my own copy of the hello_world demo. I first made a directory c:\testaws\ to put it in.

I then copied the source needed for the hello_world demo:

cd c:\testaws\
copy c:\aws\demos\hello_world*.* .

--  The famous Hello Word demo, using AWS framework.
--  Modified by JNIP to change timeout and message.

with Ada.Text_IO;

with AWS.Default;
with AWS.Server;

with Hello_World_CB;

procedure Hello_World is

   WS : AWS.Server.HTTP;

begin
   Ada.Text_IO.Put_Line
     ("Call me on port"
      & Positive'Image (AWS.Default.Server_Port)
      & ", I will stop in 5 minutes...");

   AWS.Server.Start (WS, 
                     "Hello from Graham and Jocelyn!",
                     Max_Connection => 1,
                     Callback       => Hello_World_CB.HW_CB'Access);

   delay 5 * 60.0;

   AWS.Server.Shutdown (WS);
end Hello_World;

I then created a project file, c:\testaws\hello_world.gpr:

with "aws";

project hello_world is

  for Main use ("hello_world.adb");

  for Object_Dir use "obj";

end hello_world;

AWS project files are described in the AWS User's Guide. The version of this at https://libre.adacore.com/aws/aws-gpl-2.3.0.html is out of date: it describes AWS 2.3.0, but the current version is 2.5.0. And I couldn't build the documentation for AWS on my laptop, because this requires me to install texinfo and tetex, as Pascal Obry explains in this post. However, I did find a PDF file in the docs subdirectory: on my laptop, this is c:\aws\docs\aws.pdf. This is for AWS version 2.4.0. Section 3.1.2 explains AWS project files, and is where I adapted mine from.

Having created this project file, c:\testaws\hello_world.gpr, I then made a subdirectory to hold object files, c:\testaws\obj\.

I was then able to compile my copy of hello_world, with the command:

gnatmake -Phello_world

This gave the following messages:

gcc -c -I- -gnatA C:\testaws\hello_world.adb
gcc -c -I- -gnatA C:\testaws\hello_world_cb.adb
gnatbind -shared -I- -x C:\testaws\obj\hello_world.ali
gnatlink C:\testaws\obj\hello_world.ali -shared-libgcc -Lc:\gnat\lib\aws\relocatable -laws -Lc:\gnat\lib\aws\relocatable -laws_include -Lc:\gnat\lib\aws\relocatable -laws_ssl -Lc:\gnat\lib\aws\relocatable -lz -o C:\testaws\obj\hello_world.exe

It also created an executable file c:\testaws\obj\hello_world.exe. I could run this by doing:

obj\hello_world.exe

A note about distributing stand-alone .exe files

If you're building programs to be given to others, this may be useful. In the makefile.conf, the default setting of the SHARED variable is true. This means that AWS will get built as a shared library, so that when distributing executables that use it, you'll have to distribute the AWS .dll files too.

However, if you build AWS with SHARED set to false, the libraries will get linked in when you compile your programs, and you can get away with distributing only the .exe. We have tried this: it works, and it's very useful. There is an AWS posting about this here.

New for 2011

I installed the system above in summer 2008. In January 2011, I installed a new version. Below, I explain the things I had to do differently.

1. Before downloading from https://libre.adacore.com/, I no longer needed to create an account.

2. From the list of downloads, I selected gnat-gpl-2010-1-i686-pc-mingw21-bin.exe for GNAT_GPL, and aws-gpl-2.8.0-src.tgz for AWS.

3. The Gnat installer now adds a level to the directory you put Gnat in, probably to distinguish between different versions. So my Gnat got put into c:\GNAT\2010\ , rather than c:\gnat\ .

4. Consequently, I had to add c:\GNAT\2010\bin to my PATH. Note a point mentioned below: this is where AWS installation expects to find the gcc compiler.

5. When editing the AWS makefile.conf, I had to change a variable named "prefix", setting it thus:

prefix	 = c:/GNAT/2010

6. For convenience, I list my makefile.conf in the final section at the end of this one.

7. When I tried doing

make setup

gcc -c check_config.c

This application has requested the Runtime to terminate it in an
  unusual way.
Please contact the application's support team for more information.
gprbuild: *** compilation phase failed.

export TEMP=/tmp

8. I set ADA_PROJECT_PATH to c:\GNAT\2010\lib\gnat , and ADA_INCLUDE_PATH to c:\gnat\2010\include\aws;c:\gnat\2010\include\aws\components . I had to do this before I could compile and run my AWS test program, but I can't remember whether I had to set ADA_PROJECT_PATH before the "make" would work.

9. To compile my test program, I had to do

gnatmake -gnat05 -Phello_world

My makefile.conf

This is my makefile.conf:

# This makefile includes all default values used to configure AWS. You can
# update variables here or set the corresponding variable on the command
# line. You should not have do change the main makefile.
#
# IMPORTANT: each time you change the definitions here make sure you run
#            $ make setup

##############################################################################
# AWS will be installed under $(prefix). Update this variable to point to
# the install directory. By default, it is set to the current GNAT root
# directory to have AWS project files automatically available.
#
prefix	 = c:/GNAT/2010

##############################################################################
# TARGET platform, empty for native development
#
TARGET =

##############################################################################
# Specify the default target platform to enable for installed AWS projects.
#
DEFAULT_TARGET = native

##############################################################################
# Set to true if the AWS shared runtime must be built. If ENABLE_SHARED is
# set to false only the static version is built. The default value is true if
# the platform supports shared libraries.
#
# Note that all dependents libraries (like XML/Ada) must have been compiled
# and installed as shared libraries if this option is set.
#
# ENABLE_SHARED = [true|false]
#
ENABLE_SHARED=false

##############################################################################
# Specify the default library type to setup for the installed AWS project.
#
# DEFAULT_LIBRARY_TYPE = [static|relocatable]
#
DEFAULT_LIBRARY_TYPE = static

##############################################################################
# XMLADA optional, needed if you want to build SOAP's AWS support. Set XMLADA
# to true to activate XML/Ada support, you must also set ADA_PROJECT_PATH
# to point to the XML/Ada project files if not installed in the standard
# location.
#
# XMLADA = [true/false]
#
XMLADA	= false

##############################################################################
# ASIS optional, needed if you want to build ada2wsdl tool. This tool can be
# used to create a WSDL document from an Ada spec. Set ASIS to true to
# activate ASIS support. You must also set ADA_PROJECT_PATH to point to the
# ASIS project files if not installed in the standard location.
#
# If you activate ASIS you also need to activate XMLADA above.
#
# ASIS = [true|false]
#
ASIS	= false

##############################################################################
# Zlib mandatory, check if zlib is already installed, otherwise compile the
# one coming with AWS.
#
# ZLIB = [true|false]
#
ZLIB	= $(shell $(GNAT) make -q -p \
		-Pconfig/setup/test_zlib 2>/dev/null && echo "true")

##############################################################################
# DEMOS optional, whether the demos are built or not
#
# DEMOS = [true|false]
#
DEMOS	= false

##############################################################################
# IPv6, optional. If you want to use IPv6 sockets just uncomment the IPv6
# variable below.
#
# IPv6 = [true|false]
#
IPv6	= false

##############################################################################
# AWS supports SSL (Secure Socket Layer). The SSL support is always built-in
# AWS. To build AWS's demos will SSL support you need to set SOCKET to ssl, in
# this case you must have installed OpenSSL on you computer. OpenSSL libraries
# are distributed on Windows platforms therefore the SSL mode is the default
# on this platform. (note that below ssl and openssl are aliases).
#
# SOCKET = [std|openssl|gnutls]
#
SOCKET	= std

##############################################################################
# AWS provides a binding to the LDAP API. This binding will use the standard
# LDAP DLL provided with Windows OS. On GNU/Linux you need to install OpenLDAP
# if it is not already installed. If LDAP is installed on your system you can
# set LDAP=true below.
#
# LDAP = [true|false]
#
LDAP	= false

##############################################################################
# To activate the debug mode just uncomment the variable below. This will
# build AWS with debug information and will output more build information.
#
# DEBUG = [true|false]
#
DEBUG	= false

##############################################################################
# Number of parallel compilations to do.
#
CJOBS	= 2

##############################################################################
# Tools used by AWS
#
AR 		  = ar
AWK               = awk
CHMOD	 	  = chmod
CP	 	  = cp -p
DLLTOOL	 	  = dlltool
GNAT		  = gnat
GCC		  = gcc
GPRBUILD	  = gprbuild
GPRCLEAN	  = gprclean
GREP		  = grep
GZIP	 	  = gzip
MKDIR	 	  = mkdir -p
MV	 	  = mv
PYTHON            = python
RM	 	  = rm
SED	 	  = sed
TAR	 	  = tar
WINDRES	 	  = windres
CAT		  = cat
STRIP		  = strip

UNAME = $(shell uname)

ifeq ($(UNAME), SunOS)
DIFF	=	diff -w
else
DIFF	=	diff -w -c
endif

##############################################################################
# Consistency checks

ifneq ($(DEBUG), true)
ifneq ($(DEBUG), false)
$(error DEBUG variable must be set to true or false)
endif
endif

ifneq ($(IPv6), true)
ifneq ($(IPv6), false)
$(error IPv6 variable must be set to true or false)
endif
endif

ifeq  ($(ENABLE_SHARED), )
ENABLE_SHARED=false
endif

ifeq  ($(XMLADA), )
XMLADA=false
endif

ifeq  ($(ASIS), )
ASIS=false
endif

ifeq  ($(TARGET), )
TARGET=native
endif

ifneq  ($(ZLIB), true)
ZLIB=false
endif

ifneq ($(TARGET), native)
ifeq ($(ENABLE_SHARED), true)
$(error shared libraries not supported on cross platforms)
endif
ifeq ($(ASIS), true)
$(error ASIS not supported on cross platforms)
endif
ifeq ($(LDAP), true)
$(error LDAP not supported on cross platforms)
endif
endif

ifneq ($(ENABLE_SHARED), true)
ifneq ($(ENABLE_SHARED), false)
$(error ENABLE_SHARED variable must be set to true or false)
endif
endif

ifneq ($(DEFAULT_LIBRARY_TYPE), static)
ifneq ($(DEFAULT_LIBRARY_TYPE), relocatable)
$(error DEFAULT_LIBRARY_TYPE variable must be set to static or relocatable)
endif
endif

ifneq ($(DEMOS), true)
ifneq ($(DEMOS), false)
$(error DEMOS variable must be set to true or false)
endif
endif

ifneq ($(ASIS), true)
ifneq ($(ASIS), false)
$(error ASIS variable must be set to true or false)
endif
endif

ifneq ($(XMLADA), true)
ifneq ($(XMLADA), false)
$(error XMLADA variable must be set to true or false)
endif
endif

ifneq ($(LDAP), true)
ifneq ($(LDAP), false)
$(error LDAP variable must be set to true or false)
endif
endif

ifeq ($(ASIS), true)
ifeq ($(XMLADA), false)
$(error ASIS is set and requires XMLADA to be installed. \
	You may be missing XMLADA=true)
endif
endif

ifneq ($(SOCKET), std)
ifneq ($(SOCKET), openssl)
ifneq ($(SOCKET), gnutls)
$(error SOCKET variable must be set to std, openssl or gnutls)
endif
endif
endif

ifneq ($(INSTALL), )
$(error INSTALL variable is deprecated, please use prefix instead)
endif

ifneq ($(SHARED), )
$(error SHARED variable is deprecated, please use ENABLE_SHARED instead)
endif

ifeq ("$(prefix)", "..")
$(error "Wrong install path : prefix='$(prefix)', \
  Check that GNAT is in the PATH")
else
ifeq ("$(prefix)", "")
$(error "Wrong install path : empty prefix variable")
endif
endif