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
}}}

The following table shows the output locations of generated files.

{{|
|-
! Mode
! Executable Files
! Library Files
! Include Files
|-
| release  
| ${ase}/release/bin
| ${ase}/release/lib
| ${ase}/release/inc
|-
| debug
| ${ase)/debug/bin
| $(ase)/debug/lib
| ${ase}/debug/inc
|}}

* ${ase} - 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.

{{|
|-
!
! 32 Bits
! 64 Bits
|-
| HP-UX B.11.23
| CC=cc CFLAGS="-O2 +DD32 -D_INCLUDE__STDC_A1_SOURCE" LDFLAGS="+DD32" CXX=aCC CXXFLAGS="-O2 +DD32 -D_INCLUDE__STDC_A1_SOURCE" ./configure
| CC=cc CFLAGS="-O2 +DD64 -D_INCLUDE__STDC_A1_SOURCE" LDFLAGS="+DD64" CXX=aCC CXXFLAGS="-O2 +DD64 -D_INCLUDE__STDC_A1_SOURCE" ./configure
|-
| SCO OpenServer 5.0.7 
| CC=cc CFLAGS="-Xc -a ansi -O2" ./configure
|
|-
| Solaris 10
| CC=gcc CFLAGS="-Wall -O2" CXX=g++ CXXFLAGS="-Wall -O2" ./configure
| CC=gcc CFLAGS="-Wall -O2 -m64" CXX=g++ CXXFLAGS="-Wall -O2 -m64" LDFLAGS="-m64" ./configure 
|}}

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. 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.

== 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.


== Extra Features ==

unicode
keyword replacement
error string customization

== Languages ==

{{|
|-
! Language
! Status
! Bindings
|-
| AWK
| Beta-1
| C,C++,Java,.Net
|-
| LISP
| Experimental
| C
|-
| Javascript
| Planned
| C
|}}

== AWK ==

Language Difference

{{|
|-
! ASE 
! NAWK
! REMARKS
|-
| Statement terminator Semicolon
| n/a
| n/a
|-
| function abc() 
this is very nice hello world...
| function abc ()
| n/a                          
|---------------------------------------
| return in BEGIN or END
|
|
|}}