User-defined main()

The index for the Allegro CL Documentation is in index.htm. The documentation is described in introduction.htm.

This document contains the following sections:

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
Appendix A. Potential problems with user-defined main() on Linux

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 libaclnnn.so/sl on Unix and aclnnn.dll on Windows, where nnn are digits and letters -- perhaps more than 3). 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 example below, 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",
  /* ACL shared library handle or 0 if none, 0 for this use (new in release 6.0)*/
            0,
  /* 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 elm[version].dll (the name of this file will vary, so check your ACL directory for the correct name of this .dll and the elm[version].lib). 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")'

Appendix A: Potential problems with user-defined main() on Linux

In release 5.0.1, there were problems when you built a custom executable (with a user-defined main()) on Redhat 6 caused by the fact that the Allegro shared library was built on Redhat 5. Building the custom executable on Redhat 5 resulted in a program that would run on both Redhat 5 and 6.

Allegro CL release 6.0 has Redhat 5 and 6 versions, so the Allegro library files exist for both versions. Therefore the problem described will not occur. However, when Redhat 7 becomes available, it is likely that Allegro CL for Redhat 6 will work on it okay, but it is also possible that building a custom executable (with a user-defined main()) on Redhat 7 will fail because the Allegro CL libraries are built on Redhat 6.

If you run into this problem, please contact Franz Inc. Technical Support.