qse/ase/doc/quickstart-en.man

.title ASE Quick Start Guide

= ASE Quick Start Guide =

The first step in using this library is to build it. This document shows how to build the core library on various operating systems.

== Source Code Directories ==

The source code is organized in the following directory structure.

{{{
ase +- cmn  .................... contains common functions and macros.
    +- utl  .................... contains more general-purpose utillity 
    |                            functions and macros.
    +- awk  .................... implementation of the awk processor.
    +- lsp  .................... implementation of the lisp processor.
    +- com  .................... COM wrapper of the processors.
    +- test +- awk  ............ contains test program for the awk processor.
            +- lsp  ............ contains test programs for the lisp processor.
            +- com  ............ contains test programs for the COM module.
}}}

== Unix/Linux ==

You may run the [[configure]] script on most of the supported operation systems to set up the build environment and then run the [[make]] utility.

{{{
$ ./configure
$ make 
}}}

The [[make]] utility visits each module subdirectory and build binary files. The library files are placed in the [[release/lib]] directory and the executable files in the [[release/bin]] directory.

If you appened the option [[--enable-debug]] to the [[configure]] script, the files would be located in [[debug/lib]] and [[debug/bin]] directory. Besides, it sets up the environment to be more debugging friendly.

{{{
$ ./configure --enable-debug
$ make
}}}

Refer to the following table for the output location of generated files.

{{{
---------------------------------------------------------------------------
mode     executable files     library files        include files
---------------------------------------------------------------------------
release  ${top}/release/bin   ${top}/release/lib   ${top}/release/inc
debug    ${top)/debug/bin     $(top)/debug/lib     ${top}/debug/inc
---------------------------------------------------------------------------

* ${top} - the top level directory
}}}

If you have preference for a particular compiler and the flags, you may explicitly specify them when you run the [[configure]] script. Here are presented a few such examples.

{{{
# HP-UX B.11.23 with HP C/C++ compiler
CC=cc CFLAGS="-O2 +DD64 -D_INCLUDE__STDC_A1_SOURCE" LDFLAGS="+DD64" CXX=aCC CXXFLAGS="-O2 +DD64 -D_INCLUDE__STDC_A1_SOURCE" ./configure # 64-bit
CC=cc CFLAGS="-O2 +DD32 -D_INCLUDE__STDC_A1_SOURCE" LDFLAGS="+DD32" CXX=aCC CXXFLAGS="-O2 +DD32 -D_INCLUDE__STDC_A1_SOURCE" ./configure # 32-bit

# SCO OpenServer Release 5.0.7 (SCO_SV 3.2 5.0.7) with SCO OpenServer Development System
CC=cc CFLAGS="-Xc -a ansi -O2" ./configure

# Solaris 10 with GCC
CC=gcc CFLAGS="-Wall -O2 -m64" LDFLAGS="-m64" ./configure # 64-bit
CC=gcc CFLAGS="-Wall -O2" ./configure # 32-bit
}}}

You may specify the C++ compiler with [[CXX]] and its flags in [[CXXFLAGS]].

The JNI library for JAVA is built automatically if required JNI header files are detected by the [[configure]] script. Make sure that the [[javac]] command is included in the [[PATH]] environment variable for this. The JAVA class files are built with the [[javac]] command detected as well. The {ant,http://ant.apache.org} utility from the Apache Software Foundataion can be used to build the java class files. The [[build.xml]] file is provided at the top-level directory for this.

== OpenVMS ==

You may use the [[mms]] command or the [[mmk]] command to build the library. No counterpart for the [[configure]] script is provided. As no top-level build script is provided, you have to run the command in each directory that you want to build the library in.

Let's build the AWK library and its test program, for instance.

{{{
set default [.ase.cmn]
mms
set default [-.awk]
mms
set default [-.utl]
mms
set default [-.test.awk]
mms
}}}

For those who are not familar with OpenVMS, here is one of the ways how to run the test program.

{{{
; define the foreign command.
aseawk :== $DISK$GEIN_SYS:[USERS.BACON.ASE.TEST.AWK]aseawk.exe
; run the command.
aseawk -f hello.awk
}}}

== MS-Windows ==

You may use the Visual Studio 6 or later to open the project. But you need Visual Studio 2003 or later to build the .NET related projects. Otherwise, open the command-line build environment and use the [[make]] utility.

A set of make scripts is provided to support the Microsoft build environement and the Borland build environment. The script for the Miscrosoft build environment is named [[msw-cl.mak]] while it is [[msw-bcc.mak]] for the Borland counterpart.

If you are building the AWK library and the test program, this is probably what you have to do.

{{{
cd ase\cmn
nmake /f msw-cl.mak
cd ..\awk
nmake /f msw-cl.mak
cd ..\utl
nmake /f msw-cl.mak
cd ..\test\awk
nmake /f msw-cl.mak
}}}

However, The COM module can only be built within the Visual Studio environment. After having built the COM module, you may open [[ase/test/com/asecom.vbp]] for testing.