User-defined main()

$Revision: 5.0.2.5 $

The document introduction.htm provides an overview of the Allegro CL documentation with links to all major documents. The document index.htm is an index with pointers to every documented object (operators, variables, etc.) The revision number of this document is below the title. These documents may be revised from time to time between releases.If your application requirements include running custom C code before Lisp starts up, you may build your own Lisp executable. Here is an example:

1.0 Introduction
2.0 On UNIX
2.1 Remarks on main() on Unix
3.0 On Windows
3.1 Remarks on main() on Windows

1.0 Introduction

Allegro CL consists of three standard parts and one optional part:

The Lisp main, an executable program. The responsibility of the main is to gather appropriate information and to call lisp_init with that information.

The Allegro CL Shared Library. This is a .so or .sl file on Unix and a .dll file on Windows (usually allegro.so/sl/dll). It contains lisp_init and all of the runtime system that is needed to build or attach the Lisp heap.

The Lisp heap or image. This is a .dxl file (as created by excl:build-lisp-image or excl:dumplisp) that is mapped or copied into memory and which provides the majority of Lisp and application functionality.
The optional purespace file. When used, this is a .pll file that provides sharable, read-only treatment of constant strings and codevectors.

Any Unix or Windows program may serve as a Lisp main program if it:

Gathers up proper information about the locations of all necessary files;
Links or dynamically loads the Allegro Shared Library; and
Calls lisp_init() with the appropriate arguments before trying to call any Lisp functionality.

Linking the Allegro CL Shared Library is discussed in this document. Dynamically loading the Allegro CL Shared Library is more complicated and operating-system dependent and is not further discussed. Please contact Franz Inc. for more information if you are interested in that option (see introduction.htm).

Basic requisite code for a minimal Lisp main is given in the following sections. The main should be linked with the Allegro CL Shared Library and with any other shared or static libraries that are required for Allegro CL and application operation.

2.0 On UNIX

In the below example, The <version> in libacl<version>.so is different for each release of Allegro CL. Find the correct name by looking in the Allegro directory.

struct shlib_library_item {
  char *    name;
  int        system;
};

#include <stdio.h>
#include "misc/shlibs.h"

void my_exit( int );

main( int argc, char **argv, char **envp )
{

  /* put custom installation code here */
  fprintf(stderr, "custom code runs..\n" );

  lisp_init(
  /* these three arguments are the main() arguments */
            argc, argv, envp,
  /* custom exit function; use 0 if default exit() call desired */
            my_exit,
  /* directory containing ACL shared library and Lisp image(s ) */
            "/room2/test/src",
  /* ACL shared library name; name could vary, so check your ACL
     directory for the correct name */
            "libacl<version>.so",
  /* default lisp image name; use 0 if no default desired */
            "lisp.dxl",
  /* quiet flag; if 1,  "Mapping..." message will be suppressed */
            0,
  /* Win32app flag; on UNIX, must be 0 */
            0,
  /* global variable containing prelinked library list;
     defined by shlibs.h include file */
            linked_shared_libraries ); 
}

void
my_exit( int n )
{
  fprintf( stderr, "my exit code can run here\n" );
  exit( n );
}

2.1 Remarks on main() on Unix

You most likely will not want to hardwire a pathname such as /room2/test/src. For example, you may require the user to set an environmental variable specifying the directory containing the required shared library and image; you can then call getenv() to find the needed value.
The default image name is used when there is no command line -I image name specified.
The linked_shared_libraries variable is needed for profiling, disassembly, and foreign function support. If you link your main program with additional shared libraries, add them to the shlibs.h file. For libraries that you add, set the "system" structure member to 0.
The lisp_init() function is found in the ACL shared library. After you have successfully compiled and linked your custom executable, users will have to add the directory containing the ACL shared library to their environmental variable containing the directories to be searched when a dynamic shared library load occurs.

3.0 On Windows

#include <windows.h>
#include <process.h>

unsigned _stdcall startlisp(void *x)
{
  StartLisp((char *) x, 1, 1);
}

int
WINAPI
WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine,
        int nCmdShow)
{
  HANDLE handle;
  int lisp_thread_id;

/* custom code can go here */
  MessageBox(NULL, "custom code could run now", "before Lisp starts",
             MB_OK);

  handle = (HANDLE) _beginthreadex(0, 0, startlisp, (void *) lpCmdLine, 0,
                                   &lisp_thread_id);

  WaitForSingleObject(handle, INFINITE);

/* custom code can go here; it runs after Lisp exits */
  MessageBox(NULL, "custom code could run now", "after Lisp exits",
             MB_OK);

  return 0;
}

3.1 Remarks on main() on Windows

The StartLisp() function is in the elm<version>.dll (the name of this file will vary, so check your ACL directory for the correct name of this .dll and the .lib below). Assuming the above code is in a file named testm.c, an executable named testm.exe is produced by the command: cl testm.c /Zi /MD /link elm<version>.lib user32.lib
There is no default Lisp image filename - either the user specifies one using the -I command line option, or a file dialog will pop up.
If the loaded Lisp image includes Common Graphics (and it does if it includes the Integrated Development Environment), it must be invoked like this:

testm -I allegro.dxl -e '(load "gdi32.dll")'
-e '(load "user32.dll")' -e (load "kernel32.dll")'
-e '(load "comct32.dll")'