ViewVC logotype

Contents of /skandha4/info/slisp-1

Parent Directory Parent Directory | Revision Log Revision Log

Revision - (show annotations) (download) (vendor branch)
Tue May 25 09:39:21 1999 UTC (21 years, 5 months ago) by jsp
Branch: biostr, MAIN
CVS Tags: skandha4, skandha4_1_6, dsg_1_0, HEAD
Branch point for: skandha4_pub, autoconf
Changes since 1.1: +0 -0 lines
ANSI C version of Skandha4

1 This is Info file slisp, produced by Makeinfo version 1.68 from the
2 input file slisp.texi.
4 This file documents slisp, (skandha-lisp), an extendable xlisp.
6 Copyright @copyright 1994 University of Washington Digital Anatomist
7 Program by Jeff Prothero (jsp@biostr.washington.edu) and Jim Brinkley
8 See slisp/SLISPCOPYING for details
11 File: slisp, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
13 Slisp Programmer's Online Documentation
15 Slisp (skandha lisp) is based on Xlisp, by David Betz. It consists
16 of basic xlisp, together with an organization that makes it relatively
17 easy to add new C functions to xlisp, which then become part of the
18 primitive lisp functions. This manual documents slisp, as well as
19 xlisp itself. Applications, such as skandha4, which are built on slisp,
20 are documented in their own separate nodes in the info tree, thereby
21 allowing different applications to be included at different sites. An
22 overview of the chapters is provided in the Introduction.
24 The particular slisp application(s) available at your site depends
25 on the modules that are included, but all applications will include
26 the primitive functions documented here. Additional primitive functions
27 provided in an application will be documented at the info node
28 describing that application.
30 Normally, to run an slisp application just type the name of the
31 application at the shell prompt. If it is present the basic slisp
32 application is called sl.
34 Modified for generic slisp, by Jim Brinkley, from skandha4
35 documentation by Jeff Prothero
37 * Menu:
39 * Introduction::
40 * Slisp Tutorial::
41 * Xlisp Tutorial::
42 * Xlisp Objects Tutorial::
43 * Xlisp Language Reference::
44 * Xlisp Internals::
47 File: slisp, Node: Introduction, Next: Slisp Tutorial, Prev: Top, Up: Top
49 Introduction
50 ************
52 This manual documents slisp for programmers intending to write
53 application lisp code and/or add new C-coded primitives to xlisp. This
54 manual is *not* intended for nonprogrammers who only want to use the
55 system.
57 Slisp (skandha-lisp) is an extensible version of David Betz's
58 `76704.47@CompuServe.COM' 'xlisp', a small lisp interpreter written in
59 portable C.
61 The particular xlisp version used derives from Niels P Mayer's
62 `mayer@hplnpm.hpl.hp.com' 'winterp' package for x-windows, and
63 incorporates much work by Tom Almy `toma@sail.labs.tek.com', among
64 others. It has been modified by adding hooks which make it easy to
65 add new functions to the interpreter without actually modifying the
66 interpreter source files, turning xlisp into a generic application
67 engine which can - and is - being used for a variety of applications.
68 Within our own group slisp is the basis for skandha4, a 3-D graphics
69 package; siserver, a lisp interface to a structural information
70 database, and others. We hope that by providing the basic slisp
71 environment many other similar applications will be developed.
73 Slisp uses the hybrid implementation strategy of emacs, winterp,
74 xlispstat, the Nasa Panel Library, autocad and other recent packages,
75 using a small portable lisp interpreter as a flexible high-level
76 application programming language, together with application-specific
77 C-coded primitives to provide speed and special facilities where needed.
79 Quick Overview of the chapters in this manual.
81 Slisp Tutorial
82 An introduction to Slisp, which becomes progressively more
83 detailed. How to program in LISP using an existing slisp
84 application, how to download a personal copy of slisp in order to
85 add new c functions, the file organization of slisp, how to
86 configure slisp for a new machine, how to create a new slisp
87 application, how to create a new slisp c module that is to be part
88 of an slisp application, and how to add new primitives.
90 Xlisp Tutorial
91 A simple introduction to LISP programming in xlisp. This is a
92 fairly generic introduction to lisp programming suitable for
93 programmers who haven't used the language before.
95 Programmers new to lisp will want to read this chapter thoroughly
96 and work the examples; Programmers who know lisp will probably
97 want to skim it quickly to get a feel for what xlisp does and does
98 not support.
100 Xlisp Objects Tutorial
101 A simple introduction to the object-oriented facilities of xlisp.
102 These predate the common-lisp object oriented facilities, and
103 unfortunately are quite different from the commonlisp approach.
104 On the bright side, xlisp's facilities are *much* simpler, while
105 still giving us what we really need.
107 Programmers new to xlisp will want to read this chapter thoroughly.
109 Xlisp Reference
110 Exhaustive function by function and variable by variable
111 documentation of the standard xlisp facilities, . It does *not*
112 document facilities added to xlisp by application programs such as
113 skandha4, since the same xlisp kernel is used by a number of
114 different packages, and it is important to maintain a clear
115 distinction between the invariant xlisp kernel and the
116 application-specific stuff. The slisp file hierarchy is designed
117 to allow application-specific documentation to be added as a
118 separate top level in the emacs info directory, one for each
119 separate application. However, every application will have access
120 to the basic functions documented in this chapter.
122 No sane person is likely to actually read this chapter end to end.
124 Xlisp Internals
125 The internal workings of the xlisp core interpreter. You certainly
126 don't need to read this if you are just writing lisp code, and you
127 shouldn't need to understand most of it even if you are adding new
128 C primitives.
131 File: slisp, Node: Slisp Tutorial, Next: Xlisp Tutorial, Prev: Introduction, Up: Top
133 Slisp Tutorial
134 **************
136 This chapter describes how to get started programming in Slisp,
137 sharing slisp source code, the basic organization of slisp, methods for
138 creating new applications, and basic methods for adding new primitive
139 functions to xlisp.
141 Section overview. The items are presented in order of increasing
142 detail, beginning with programming in LISP only, and ending with adding
143 new primitive c-coded functions to slisp.
145 Lisp Programming in Slisp
146 Basic procedures for LISP programming, for programmers who will be
147 writing LISP code using an existing compiled slisp application
148 such as sl.
150 Sharing Slisp code
151 Describes our current methods for sharing slisp code at our site.
152 How we've set up our source code archive, methods for copying a
153 version of slisp into your personal directory, and methods for
154 handling multiple machine architectures accessing a common nfs
155 mounted source directory. We also discuss tradeoffs between this
156 and other sharing schemes such as CVS, that we have not yet
157 implemented.
159 Slisp Organization
160 The overall file structure of slisp.
162 Configuring a Machine
163 How to configure slisp to run on a given machine.
165 Creating a New Application
166 How to compile a set of existing modules into a new application.
168 Creating a New Module
169 How to create a new module that can be included in an
170 application, where a module contains the c code to create
171 additional lisp primitive functions.
173 Creating New Primitives
174 How to create additional lisp primitives within a module.
176 Embedding Slisp in C
177 How to include Slisp in a larger C program
179 Client-Server Operations
180 Using slisp over a network
182 History:
183 Created 10/8/93 by jfb (Jim Brinkley)
185 Modified 10/3/94 by jfb. Added client-server operations
187 Modified 3/17/95, jfb. Added ScopyFiles and SinstallFiles
189 * Menu:
191 * Lisp Programming in Slisp::
192 * Sharing Slisp Code::
193 * Slisp Organization::
194 * Configuring a Machine::
195 * Creating a New Application::
196 * Creating a New Module::
197 * Creating New Primitives::
198 * Embedding Slisp in C::
199 * Client-Server Operations::
202 File: slisp, Node: Lisp Programming in Slisp, Next: Sharing Slisp Code, Prev: Slisp Tutorial, Up: Slisp Tutorial
204 Lisp Programming in Slisp
205 =========================
207 Most programmers will simply want to program in lisp, rather than
208 create new primitive C functions. The simplest way to do this is to
209 simply type the name of an slisp application installed at your site, in
210 a shell. For example type sl, for the basic slisp application that
211 contains the xlisp primitives. Of course, like any other Unix
212 application, sl must be available from your PATH variable.
214 Slisp (and Xlisp) uses an environment variable called XLPATH, which
215 is a search path for loading lisp files. At our site this path is
216 defined for all users (in applications installed in /usr/local/bin) to
217 be /usr/local/xlisp, so any files in this directory can be loaded just
218 by typing (LOAD-LIBRARY file) in the application.
220 If you change XLPATH then the search path can be customized. For
221 example, if init.lsp is present in the initial XLPATH then this file
222 will always be loaded at startup, which you may not want. Instead if
223 you set XLPATH to be mypath:$XLPATH, slisp will first search for files
224 in mypath before it searches the original XLPATH. This means you can
225 have your own init.lsp file which will be loaded instead of the system
226 init.lsp file, or you can preferentially load custom copies of lsp
227 files that are part of a larger system.
229 In order to setup your own XLPATH look at the executable file for
230 the application you are using. For the basic slisp application sl, this
231 file is called sl, and is probably installed in /usr/local/bin. If not
232 ask the person who installed slisp at your site.
234 The file app (the executable file whose name is the name of the
235 application) is actually a shell script which first sets XLPATH, then
236 executes the binary file, which is app.bin, or in the case of sl,
237 sl.bin. To create your own XLPATH copy app to your own directory, then
238 change XLPATH to be whatever you want it to be.
240 You can also change the name of this file if you want its name to
241 reflect a specific application that adds lisp files. For example, one
242 application we have is called siserver, which includes c modules to
243 access a database system. To make a special bibliographic retrieval
244 application that uses the database it might be reasonable to rename
245 siserver to bib, set XLPATH within the shell script bib to include any
246 lisp directories containing files you want dynamically loaded, and
247 include on the line that calls siserver.bin any lisp files you want to
248 always load at runtime.
250 Once the basic structure of an slisp application is set up the rest
251 is simply lisp programming. For a basic tutorial about the xlisp
252 primitive functions and object oriented extensions that are available
253 in every slisp application see Xlisp Tutorial and Xlisp Objects
254 Tutorial. For a complete reference of xlisp functions see Xlisp
255 Reference. For descriptions of additional primitive functions that are
256 added for specific applications see the info node associated with that
257 application.
260 File: slisp, Node: Sharing Slisp Code, Next: Slisp Organization, Prev: Lisp Programming in Slisp, Up: Slisp Tutorial
262 Sharing Slisp Code
263 ==================
265 This section describes how we have set up slisp for sharing in the
266 Digital Anatomist Program. This is somewhat specific for our program,
267 but it may give ideas for other sites. At the end of this node we
268 describe tradeoffs and other ideas we haven't had time to pursue yet.
270 In the Digital Anatomist Program all relevant machines have
271 /usr/local/src mounted from a single machine (betz). The archive copy
272 of slisp is kept in this directory as /usr/local/src/slisp. This
273 directory should be visible from the machine on which you are planning
274 to use slisp. Even if it isn't a copy of slisp can be made for your own
275 machine if necessary.
277 The basic approach we currently use is to keep usr/local/src/slisp
278 as the archive directory for sharing changes to slisp, but each
279 programmer downloads a copy of the relevant modules from the archive,
280 and compiles an application from within his own directory.
282 Once the local version has been verified the programmer uploads his
283 changes into the archive and notifies the other programmers by email in
284 person that he has done this. The other programmers can then download
285 the changed files to their own personal copies of slisp. Only members
286 of the slisp unix group may write to the archive but anyone can read
287 from it.
289 In the following menu items, Downloading and Uploading refer to
290 entire slisp applications such as skandha4, sl or siserver. If you just
291 want to upload or download individual files or directories, or if you
292 want to install a list of lisp files in a common location, see the menu
293 item for Copying Individual Files.
295 * Menu:
297 * Downloading::
298 * Uploading::
299 * Copying Individual Files::
300 * Sharing Issues::
303 File: slisp, Node: Downloading, Next: Uploading, Prev: Sharing Slisp Code, Up: Sharing Slisp Code
305 Downloading
306 ===========
308 In the following let Archive=/usr/local/src, or a similar path that
309 refers to the location of the slisp sharable archive. Let
310 Local=$HOME/src, or a similar path that refers to your personal copy of
311 slisp in your home directory.
313 To aid in downloading a local version of slisp, a script called
314 Scopy is located in Archive/slisp/bin. To run this script cd to the
315 archive subdirectory in which the application you are interested in
316 resides (e.g. Archive/slisp/sl), then run Scopy Local. The result
317 will be that a directory hierarchy called Local/slisp will be created,
318 and only those slisp modules required for the application will be
319 copied. The basic application sl will always be copied, but the sl
320 directory is very small.
322 This assumes Scopy is in your search path. It is useful in general
323 to include Local/slisp/bin in your search path, (which will include
324 Scopy once the initial download has been made) since the other
325 configuration scripts reside there as well.
327 If Local/slisp already exists then files of the same name will be
328 replaced from the archive copies. Thus, Scopy can be used to update
329 your personal copy of Slisp after someone else has made changes. Of
330 course it would be prudent to see what the changes are before you
331 delete your own copies. This can be done on many machines by running
332 diff -r Archive/slisp Local/Slisp, which will recursively list all the
333 differences between the two directories.
336 File: slisp, Node: Uploading, Next: Copying Individual Files, Prev: Downloading, Up: Sharing Slisp Code
338 Uploading
339 =========
341 In the following let Archive=/usr/local/src, or a similar path that
342 refers to the location of the slisp sharable archive. Let
343 Local=$HOME/src, or a similar path that refers to your personal copy of
344 slisp in your home directory.
346 To merge your changes back into Archive/slisp Scopy can be used in
347 the reverse direction. That is, cd to your local copy of the
348 application directory you are working with (e.g. Local/slisp/sl), and
349 run Scopy Archive, which will replace the archive copies with your
350 files of the same name, leaving other archive files unchanged. This
351 assumes you have write priviledges in Archive.
353 Before you do this please add a description of your changes to the
354 front of Local/slisp/Changelog.txt, which will then replace the version
355 in Archive. It is also important to not upload your changes before you
356 have donwloaded someone else's changes or you will overwrite them.
357 Since we are not yet using a revision control system we need to
358 communicate often with each other.
361 File: slisp, Node: Copying Individual Files, Next: Sharing Issues, Prev: Uploading, Up: Sharing Slisp Code
363 Copying Individual Files
364 ========================
366 The sections on uploading and downloading assume you want to move
367 entire Slisp applications. If you are just interested in uploading or
368 downloading individual files or directories you can use two additional
369 scripts, both of which are in slisp/bin. These scripts are ScopyFiles
370 and Sinstallfiles
372 Scopyfiles is used to copy a list of files from a source slisp
373 hierarchy to the same relative positions in a destination hierarchy.
374 Thus, if you make changes in only a few files in your local copy of
375 Slisp you can run this file to upload just those files to the archive.
376 The script appends the list of changed files to a file called
377 ChangedFiles in the destination. This list can be cut and pasted into a
378 filelist as input to this script, so that others can download just the
379 changed files to their own local copies.
381 The syntax for this script is:
383 ScopyFiles sourcepath destpath filelist
385 sourcepath is the path to the root of the source slisp hierarchy,
386 eg., /usr/people/brinkley/src/slisp.
388 destpath is the path to the root of the destination slisp hierarchy,
389 e.g., /usr/local/src/slisp
391 filelist is a list of pathnames relative to the source and
392 destination hierarchies. Each file in filelist can be either a file or
393 a directory.
395 The second script is Sinstallfiles. This script has the same syntax
396 as ScopyFiles, except all entries in filelist must be files, not
397 direcctories. All files in filelist are copied to the same level in the
398 destination directory. This is useful for installing lisp files that
399 are all meant to be at the same level in a lisp search directory for
400 slisp applications.
402 For example destpath in our case will usually be /usr/local/xlisp,
403 since this is the path for loading lisp files in our local environment.
406 File: slisp, Node: Sharing Issues, Prev: Copying Individual Files, Up: Sharing Slisp Code
408 Sharing Issues
409 ==============
411 This method of code sharing is based on the ideas used in CVS,
412 concurrent versions systems. I (jfb) tried to get CVS working for slisp
413 but found that, although it worked, it was very unforgiving when I made
414 a mistake or when I deleted or renamed a directory. Perhaps someone
415 else can get this working, since our current approach does not allow
416 for revision control, which will have to be done for now just by
417 freezing versions of the entire slisp archive in seperate compressed
418 tar files.
420 Another approach that I looked at was allowing the slisp archive to
421 be shared while code was being compiled. That is, a programmer would
422 only have local copies of those modules he was modifying, and would
423 link to source code in the nfs mounted archive.
425 The advantages of this are 1) only a single copy of shared code
426 would exist, and 2) some space would be saved.
428 The disadvantages are 1) this mechanism is not yet implemented and
429 we've spent too much time on this already 2) Any change added by a
430 programmer to the shared archive will be immediately seen by all others
431 who use the archive, which may mean that a person's application will
432 break 3) If a programmer desires to download a version of slisp that is
433 not on the net then the shared archive will also have to be
434 downloaded.
436 The main reason we didn't look at this alternative is that it would
437 take time to implement, and we first need to see how useful slisp will
438 be before we make it work better. This whole area is of course related
439 to CASE, and we probably should be implementing this all in some
440 commercial CASE tool.
443 File: slisp, Node: Slisp Organization, Next: Configuring a Machine, Prev: Sharing Slisp Code, Up: Slisp Tutorial
445 Slisp Organization
446 ==================
448 This node describes the basic organization of the slisp file
449 hierarchy. This same organization will be found in the slisp archive
450 and in all downloaded copies.
452 Slisp is organized as a file directory called slisp consisting
453 mostly of a set of modules, each contained within a subdirectory. One
454 of the modules is xcore, the basic xlisp interpreter written by Dave
455 Betz. Each of the other modules (each starting with x, i.e. xetc) is a
456 set of c and or lsp functions for implementing a new module.
458 An slisp application is defined by a subdirectory within slisp (say
459 sl, for the basic sl application), whose name is the name of the
460 application, and which contains configuration information,
461 documentation, and generated files specific to the application. This
462 organization allows more than one application to be built within the
463 same directory hierarchy by simply creating a new application directory.
465 The files within each application directory are described in *Note
466 Creating a New Application::.
468 The files within each module are described in *Note Creating a New
469 Module::.
471 The following additional files and directories are present in all
472 slisp distributions:
474 * bin
476 Sconfigure - configure a new machine.
478 Smake - configure a new application.
480 Scopy - Download or upload an slisp application to a local
481 directory for compiling.
483 make_tags - make tags for emacs
485 * c - functions and main programs independent of any module
487 seval.c - routines for embedding slisp in C as a local client
489 netseval.c - analogous routines for running slisp over a network
491 sl_client. - main program for creating example network and local
492 clients
494 client_check.c - check routines for local and network clients
496 * Changelog.txt - Changes in overall slisp. This should be added to
497 by programmers to document the changes to slisp that they upload
498 to the shared archive.
500 * doc - miscelaneous documentation not in info format
502 * include - global h files needed by more than one module
504 * info
506 Global documentation in texi format that is formatted by the
507 program makeinfo from the Free Software Foundation. All info
508 nodes below the slisp node, including the node you are reading
509 now, are created from source files in this directory.
511 * lsp
513 Global lsp files of use to more than one application. In
514 particular slispinit.lsp contains useful functions, test*.lsp are
515 used by make check to test individual modules, and classes.lsp
516 contains macros for easier manipulation of the xlisp object system.
518 * Makefile.x - a section of make targets that is included by the
519 Makefiles in each module.
521 * README - general organization of slisp
523 * sl
525 The basic slisp application sl. This directory can be used as a
526 template for creating other applications. Each application is
527 defined by a subdirectory of slisp whose name is the name of the
528 application.
530 * systems
532 Files defining the characteristics of machines on which slisp is
533 designed to run. One of these files is read by Sconfigure to
534 configure a machine for slisp. In theory the systems information
535 should be independent of the applications information. This is not
536 yet actually the case. An example is that our NeXT file contains
537 in the variable OTHERLIBES the sybase library, which is needed by
538 the module xsybase.
540 * util - General purpose utility routines
542 In addition to the directories within the slisp hierarchy, the
543 configuration scripts Sconfigure and Smake will create files within
544 $HOME/bin and $HOME/lib. The idea is that no derived files (such as o
545 files or libraries) should be created in the source slisp directory, so
546 that multiple machines can access a single nfs mounted source
547 directory, yet create machine and application-specific binary files.
548 The files created are:
550 * $HOME/bin
552 appname - a shell script that sets XLPATH, then calls appname.bin,
553 where appname is the name of an application (e.g. sl).
555 appname.bin - the executable for appname
557 * $HOME/lib
559 Makefile.def - Machine specific definitions created by Sconfigure
561 Makefile.lastapp - The last application compiled. Needed by make
562 check in order to know which application to run when checking test
563 code for a module.
565 slisp-host - a link to slisp/systems/host, created by Sconfigure
567 libslisp.a - library of all o files for all modules except xcore.
568 This library is shared by all applications.
570 libapp.a (e.g. libsl.a for the basic slisp application) - xcore
571 routines that were compiled for a specific application. The basic
572 approach to adding new c primitives into xlisp is to re-compile
573 xcore and include the new c code, so xcore will be different for
574 each application.
577 File: slisp, Node: Configuring a Machine, Next: Creating a New Application, Prev: Slisp Organization, Up: Slisp Tutorial
579 Configuring a Machine
580 =====================
582 Once a copy of slisp has been downloaded to your local directory, it
583 must be configured to run on your local machine. To do this run
584 slisp/bin/Sconfigure machine, where machine is the name of a machine
585 defined by a file in slisp/systems. In this case and in all subsequent
586 discussion slisp refers to the downloaded slisp directory that is in
587 your local HOME directory.
589 Sconfigure will read the information in the machine file and create
590 the appropriate HOME/lib files as outlined in the previous node. If a
591 file for your machine does not exist create one by copying an existing
592 one, renaming it to an appropriate name for your machine, and setting
593 the variables appropriately. All variables must be set. Of course we
594 can't guarantee that slisp will run on any machine, but we hope that it
595 will be as portable as Xlisp is.
598 File: slisp, Node: Creating a New Application, Next: Creating a New Module, Prev: Configuring a Machine, Up: Slisp Tutorial
600 Creating a New Application
601 ==========================
603 A new application is created by creating a new copy of an existing
604 application directory and naming it app (where app is the application
605 name). The basic slisp application sl is useful as a template for
606 creating new applications.
608 Within slisp/app, edit the modules file to determine which x modules
609 are included, edit install_aux for installing any special files in the
610 install locations, and edit the documentation in the info directory.
612 The documentation file is built from app/info/Makefile. The
613 documentation consists of several files that are included in the top
614 level, which is generally called app.texi (eg sl.texi for the basic
615 slisp application). This file then includes intro.texi, which
616 introduces the application, a tutorial (if present) and ref.texi which
617 is built automatically from the included files. The reference file is
618 begun by ref.header, which always must exist with the name ref.header,
619 but which can be customized for the application.
621 The script slisp/bin/Smake is then run to configure a Makefile and
622 auxiliary files for the application, which are saved within the
623 application directory. This script must be run from within slisp/app,
624 where app is the name of the application.
626 Once the app is configured it is built by the following:
628 1. cd to slisp/app
630 2. make clobber, to remove any previous versions
632 3. make all, to make the application and the documentation
634 4. make check, runs various test routines and writes the log in
635 app/check.log.
637 5. make install, (as root) installs the application, documentation
638 and loaded lsp files in directories specified in the system file.
641 File: slisp, Node: Creating a New Module, Next: Creating New Primitives, Prev: Creating a New Application, Up: Slisp Tutorial
643 Creating a New Module
644 =====================
646 A new module is created by copying an existing module and editing
647 the files appropriately. A good module to use for this purpose is xetc,
648 looking at xcore/doc/mymodule.h for ideas on how to create new xlisp
649 primitives. Also XlispInternals has at the end a discussion of how to
650 add new primitives.
652 In the following, let xmodule be the name of the module which is
653 also the name of the subdirectory under slisp. I.e. for xetc, xmodule =
654 xetc.
656 The following subdirectories and files must be present in every
657 module. All files are given relative to slisp/xmodule.
659 * c - C source code plus header files.
661 * c/Makefile
663 Overall makefile for the module. Must contain the targets clean
664 and xlisplibmore. xlisplibmore is a placeholder for additional
665 commands that should be performed when xlisplib is reached, which
666 is defined in Makefile.x at the top level. An example is the
667 command in xgt to make the distribution makefile. XLISPLIBOBJS is
668 a list of o files that are to be included in the module.
670 * c/xmodule.h
672 The master include file for the module, a subset of mymodule.h,
673 may be empty but must exist. The name must be xmodule.h (ie
674 xetc.h).
676 * check - Location of regression tests to make sure a module is
677 installed correctly.
679 * check/Makefile
681 Must exist and contain the targets test and clean.
683 * info - location of info documentation files used to build the
684 reference manual for an application.
686 * info/xmodule.texi
688 Documentation in texi format. May be empty but must exist.
690 * info/xmodule.menu
692 Info menu item for reference manual. May be empty but must exist.
694 * lsp
696 Lisp files for the module. May be empty but must exist.
698 Other subdirectories may be present but do not need to be.
701 File: slisp, Node: Creating New Primitives, Next: Embedding Slisp in C, Prev: Creating a New Module, Up: Slisp Tutorial
703 Creating New Primitives
704 =======================
706 Not done. For now look at Xlisp Internals:"How do I add a new
707 primitive fn to xlisp?" , xcore/doc/mymodule.h, and of course source
708 code in the various modules.
710 One important point when adding new primitives. It is essential that
711 LVALS be protected with xlsave or xlprotect. If not the garbage
712 collector may try to collect them at inopportune times, with the result
713 that you will get very obscure bugs, often causing your program to
714 hang. Similarly it is essential to pop all saved variables off the
715 evaluation stack when exiting your function (except when you call
716 xlfail for an error, since the stack is cleared for you). Otherwise the
717 garbage collector will later try to access a NULL pointer, often
718 causing a segmentation fault. Based on our experience, if you get
719 strange, almost untraceable bugs, they are almost certainly due to
720 improperly protecting or releasing LVALS. Worse yet these bugs can
721 happen in your own application even if your module is ok but someone
722 elses module doesn't properly protect LVALS.
724 The section on Xlisp Internals mentioned above discusses this in
725 more detail.
728 File: slisp, Node: Embedding Slisp in C, Next: Client-Server Operations, Prev: Creating New Primitives, Up: Slisp Tutorial
730 Embedding Slisp in C
731 ====================
733 The files /include/seval.h and /c/seval.c allow slisp to be
734 included as part of other C programs, so that it can be controlled in a
735 different manner than the read-eval-print cycle that is used in xmain,
736 the main program in xlisp. The primary motivation for this is to allow
737 slisp to be controlled from a graphical user interface. For example, an
738 slisp application could become a module within AVS, (Advanced
739 Visualization System), or an object within a NeXTStep application.
741 The main routines are sl_Init, to initialize slisp, and sl_Eval_Str,
742 which accepts a string describing an s-expression, calls slisp to
743 evaluate it, and writes the results to an output string pointer (memory
744 for the output string is allocated by seval.c). Slisp errors are
745 written to the output string. There are also routines to get the C
746 integer, float or string value of the current LISP expression. Since
747 all of Slisp is supported, all primitive functions are available, as
748 are any LISP functions via the LOAD lisp command.
750 Note that seval.c always disables debugging and tracing even if the
751 lisp programmer sets *BREAKENABLE* or *TRACENABLE* to T. This is
752 because the debug loop in xlisp requires more input, which is
753 incompatible with the notion of sending all input in a string, and then
754 receiving all output in another string.
756 The externally callable functions are defined in seval.h, which
757 should be included in the external program, along with a compiler
758 directive -I$(SLISPROOT)/include to find the include file, where
759 SLISPROOT is the location of the top level slisp directory. The main
760 program should be linked with up to four libraries: LOCALLIBES
762 libraries are automatically created in the LIBPATH directory, which is
763 specified in the appropriate slisp/systems file.
765 LOCALLIBES is libseval.a, and is the library for the routines in
766 seval.c.
768 XCORELIBES are the routines from xcore that implement the basic
769 xlisp functions designed by Dave Betz. This library is different for
770 each application. For sl the library is called libsl.a.
772 XLISPLIBES is the common library containing all new c-coded
773 primitive functions added to slisp by any compiled application. This
774 file is called libslisp.a.
776 NETLIBES contains analogous routines to seval.c, defined in
777 c/netseval.c, that allow an slisp application to act as a network
778 client for another slisp server (see the section on client-server
779 operations). This library is only required if the application being
780 embedded has been compiled with the xnet module.
782 OTHERLIBES are any other libraries potentially needed by an
783 application on a given machine, as defined in the appropriate
784 slisp/systems file.
786 slisp/c contains the source code for seval.c, as well as an example
787 embedded application. The Makefile for each application has a target
788 called "local_client". When this target is made the c/Makefile is used
789 to compile an example local client whose name is appc, where app is the
790 name of the executable shell for the application. For example, for sl
791 the local client is slc.
793 For the local client c/Makefile defines LOCAL_CLIENT, and compiles
794 c/sl_client.c. This program can be used as a template for including the
795 seval.c functions.
797 In addition when "make check" is run for an application, the
798 c/Makefile "check" target is run, which creates an executable
799 "local_check" from client_check.c. client_check.c provides examples
800 for using the routines in seval.c.
802 A somewhat simpler example is shown below, which is essentially the
803 same as sl_client.c, but without all the makefile flags.
805 # Example Makefile that searches libraries in HOME/lib
806 # which is where the slisp libraries are created by default.
807 # Search application library sl before slisp
808 LIBS= -L$HOME/lib -lseval -lsl -lslisp -lnetseval
809 CFLAGS= -I$HOME/src/slisp/include #location of seval.h
811 slc:slc.o
812 cc slc.o $(LIBS) -o slc
814 /******************************************************************/
815 /* slc.c */
818 #include "seval.h"
819 #include <stdio.h>
821 #define BUF_SIZ 4000
823 /* Example main program that uses the functions in seval.h */
824 /* to implement a read-eval-print loop to the terminal. sl_Init */
825 /* and sl_Eval_Str are the two routines from seval.h. */
826 /* Note that we don't include */
827 /* a newline in our prompt, since the slisp return */
828 /* values always end with a newline anyhow, following */
829 /* the convention used in other xlisp routines. */
831 main()
832 {
833 char inbuf[ BUF_SIZ ];
834 sl_Init();
835 for (;;) {
836 int got_err;
837 char* result, *out;
838 /* Read string to evaluate from user: */
839 printf("> ");
840 fgets( inbuf, BUF_SIZ, stdin );
841 /* Evaluate the string: */
842 out = sl_Eval_Str(&got_err, &result, inbuf );
843 /* If out != result then the evaluated */
844 /* function printed some output before */
845 /* returning, as for example from a PRINT */
846 /* or FORMAT function call */
847 if (out != result) printf("%s", out);
848 /* If an error was returned by slisp */
849 /* got_err will be true. The error messages */
850 /* are not prepended by "error: " because */
851 /* some programs may not want this. But to */
852 /* be consistent with slisp conventions the */
853 /* error message should be prepended with */
854 /* error: */
855 /* If an error was not received then result */
856 /* has the string equivalent of the value */
857 /* returned by the function */
858 if (got_err)
859 printf("error: %s", result);
860 else
861 printf("%s", result);
862 }
863 }
866 File: slisp, Node: Client-Server Operations, Prev: Embedding Slisp in C, Up: Slisp Tutorial
868 Client-Server Operations
869 ========================
871 A tcp-based network protocol has been designed which allows a
872 client to evaluate s-expressions via an slisp server running on a
873 remote machine. Any compiled slisp application may be run as a server,
874 and an application compiled with the xnet module may be run as a
875 client. A network client that is embedded in a C program may also be
876 created.
878 * Menu:
880 * Server Mode::
881 * LISP Network Client::
882 * Embedded Network Client::
885 File: slisp, Node: Server Mode, Next: LISP Network Client, Up: Client-Server Operations
887 Server Mode
888 -----------
890 Any slisp application may be run in server mode by starting it with
891 the -s flag. The -s flag causes the application to supress the initial
892 prompt, and to enclose output in control character delimiters that
893 allow the client to disambiguate error and other output from the value
894 returned by the function.
896 The program can be made into a network accessible server by
897 including it as one of the programs known to the internet superserver
898 inetd. The operations for accomplishing this must be done by root on
899 the server machine. The following operations use as an example the
900 creation of a server for the basic slisp application sl, on port 5201:
902 1. Read about inetd and services by doing man inetd and man
903 services.
905 2. Choose a port number, an application name (usually the name of
906 the executable), and a user under whom the application should run. Port
907 numbers above 5000 are usually safe. The user should not be root since
908 slisp contains the "system" command which under root could do almost
909 anything. An ordinary user is usually best, or one that is created for
910 the server.
912 3. Make an entry in /etc/services for the port number, application
913 name and protocol (tcp). For example, to run the basic slisp
914 applications sl as a server on port 5201:
916 sl 5201/tcp
918 4. Make an entry in /etc/inetd.conf to tell inetd which program to
919 run when a connection is made on the given port with the service name
920 defined in /etc/services:
922 sl stream tcp nowait slisp /usr/localbin/sl sl -s
924 The fields are separated by spaces or tabs. For this example the
925 fields are:a) sl - the name of the service defined in /etc/services b)
926 stream, tcp and nowait - should always be set to these for this
927 protocol c) slisp - the name of the user under which the server should
928 run. Here we've created a pseudo user called slisp, d)
929 /usr/localbin/sl, the pathname to the executable - note this can be the
930 executable shell script. Environment variables set by the shell script
931 are remembered by the server, e) sl - The first argument, always the
932 name of the executable, f) -s - any remaining arguments.
934 The appropriate man pages have more information.
937 File: slisp, Node: LISP Network Client, Next: Embedded Network Client, Prev: Server Mode, Up: Client-Server Operations
939 LISP Network Client
940 -------------------
942 If an slisp application is compiled with the xnet module it can be a
943 client to an slisp server. Lisp primitives defined in xnet.c setup a
944 connection to the remote server, and allow control over the delimiters
945 and the timeout. Once the connection has been established an
946 s-expression may be evaluated on the remote server by the function
947 NET-EVAL, which is nearly the same as the ordinary LISP EVAL function.
948 The results of the NET-EVAL function are available within the local
949 slisp process as long as the results don't include pointers to objects
950 in the remote memory space.
952 The xnet functions are described in the reference part of the info
953 documention for any application compiled with xnet.
956 File: slisp, Node: Embedded Network Client, Prev: LISP Network Client, Up: Client-Server Operations
958 Embedded Network Client
959 -----------------------
961 xnet utilizes c functions defined in slisp/c/netseval.c, which are
962 compiled by every application into the library libnetseval.a. If this
963 library is linked with any C program the C program can call the
964 functions in netseval.c to evaluate s-expressions on a remote server.
965 The functions in netseval.c are semantically equivalent to those in
966 seval.c (described in the section on embedding lisp in C), with the
967 addition of functions for establishing a connection.
969 c/sl_client.c, when compiled with the NET_CLIENT flag, creates a
970 network client called netsl. netsl is created whenever the net_client
971 target is made in an application Makefile. c/client_check.c, when
972 compiled with the NET_CLIENT flag by the check target in each
973 application Makefile, also shows an example of an embedded network
974 client.
976 Since for a network client all of slisp is located on the server,
977 the only library that needs to be linked into a C program is
978 libnetseval.c, which is shown in the c/Makefile for the target
979 net_client.
981 A somewhat simpler example is shown below, which is essentially the
982 same as sl_client.c, but without all the makefile flags. This is also
983 very similar to slc, the main program described under embedding lisp in
984 C.
986 # Example Makefile that searches libraries in HOME/lib
987 # which is where the slisp libraries are created by default.
988 # Search application library sl before slisp
989 LIBS= -L$HOME/lib -lnetseval
990 CFLAGS= -I$HOME/src/slisp/include #location of netseval.h
992 netsl:netsl.o
993 cc netsl.o $(LIBS) -o netsl
995 /******************************************************************/
996 /* netsl.c */
999 #include "netseval.h"
1000 #include <stdio.h>
1002 #define BUF_SIZ 4000
1004 /* Example main program that uses the functions in netseval.h */
1005 /* to implement a read-eval-print loop to the terminal. */
1006 /* Functions starting with sn_ are the routines from netseval.c */
1007 /* Note that we don't include */
1008 /* a newline in our prompt, since the slisp return */
1009 /* values always end with a newline anyhow, following */
1010 /* the convention used in other xlisp routines. */
1012 main()
1013 {
1014 char inbuf[ BUF_SIZ ];
1015 int s;
1016 sl_Init();
1017 if (!(argc == 3)) {
1018 printf("Usage: %s <hostname> <port number>\n", argv[0]);
1019 exit(1);
1020 }
1021 s = sn_Connect(argv[1], atoi(argv[2]), &got_err, &result, &err);
1022 if (got_err) {
1023 if (result)
1024 printf("%s", result);
1025 printf("error: %s", err);
1026 printf("Can't connect to %s on port %s\n", argv[1], argv[2]);
1027 exit(1);
1028 }
1029 printf("%s", result);
1030 sn_Set_Socket(s);
1031 for (;;) {
1032 int got_err;
1033 char* result, *out;
1034 /* Read string to evaluate from user: */
1035 printf("> ");
1036 fgets( inbuf, BUF_SIZ, stdin );
1037 out = sn_Eval_Str(&got_err, &result, inbuf );
1038 if (out != result) printf("%s", out);
1039 if (got_err) {
1040 if (!strcmp(result, "Server timeout\n") ||
1041 !strcmp(result, "Connection not open\n")) {
1042 printf("%s", result);
1043 exit(0);
1044 }
1045 else
1046 printf("error: %s", result);
1047 }
1048 else
1049 printf("%s", result);
1051 }
1052 }
1055 File: slisp, Node: Xlisp Tutorial, Next: Xlisp Objects Tutorial, Prev: Slisp Tutorial, Up: Top
1057 Xlisp Tutorial
1058 **************
1060 Copyright
1061 =========
1063 This chapter is adapted from an 'xlisp.doc' file with the following
1064 copyright:
1066 XLISP: An Object-oriented Lisp
1068 Version 2.1 (WINTERP)
1070 April 23, 1989
1072 by
1074 David Michael Betz
1076 P.O. Box 144
1078 Peterborough, NH 03458
1080 (603) 924-4145 (home)
1082 Copyright (c) 1989, by David Michael Betz
1084 Note: This document has been updated to include new lisp primitives
1086 added by the WINTERP distribution of XLISP 2.1.
1088 WINTERP 1.0 Copyright 1989 Hewlett-Packard Company (by Niels Mayer).
1090 $Header: /usr/local/cvsroot/src/slisp/info/xlisptut.texi,v 1998/06/20 03:54:55 ben Exp $
1092 * Menu:
1094 * Xlisp Tutorial Introduction::
1095 * Note From Author::
1096 * Xlisp Command Loop::
1097 * Break Command Loop::
1098 * Data Types::
1099 * The Evaluator::
1100 * Lexical Conventions::
1101 * Readtables::
1102 * Lambda Lists::
1103 * Objects::
1104 * Class Object::
1105 * Class Class::
1106 * Symbols::
1107 * Evaluation Functions::
1108 * Symbol Functions::
1109 * Property List Functions::
1110 * Array Functions::
1111 * List Functions::
1112 * Destructive List Functions::
1113 * Predicate Functions::
1114 * Control Constructs::
1115 * Looping Constructs::
1116 * Progs And Blocks::
1117 * Debugging And Error Handling::
1118 * Arithmetic Functions::
1119 * Bitwise Functions::
1120 * String Functions::
1121 * Character Functions::
1122 * I/O Functions::
1123 * Format Function::
1124 * File I/O Functions::
1125 * String Stream Functions::
1126 * Structures::
1127 * System Functions::
1128 * File I/O Examples::
1129 * Unix I/O Functions::
1132 File: slisp, Node: Xlisp Tutorial Introduction, Next: Note From Author, Prev: Xlisp Tutorial, Up: Xlisp Tutorial
1134 Introduction
1135 ============
1137 XLISP is an experimental programming language combining some of the
1138 features of Common Lisp with an object-oriented extension capability.
1139 It was implemented to allow experimentation with object-oriented
1140 programming on small computers.
1142 There are currently implementations of XLISP running on the IBM- PC
1143 and clones under MS-DOS, on the Macintosh, the Atari-ST and the Amiga.
1144 It is completely written in the programming language 'C' and is easily
1145 extended with user written built-in functions and classes. It is
1146 available in source form to non-commercial users.
1148 Many Common Lisp functions are built into XLISP. In addition, XLISP
1149 defines the objects 'Object' and 'Class' as primitives. 'Object' is the
1150 only class that has no superclass and hence is the root of the class
1151 heirarchy tree. 'Class' is the class of which all classes are instances
1152 (it is the only object that is an instance of itself).
1154 This document is a brief description of XLISP. It assumes some
1155 knowledge of LISP and some understanding of the concepts of
1156 object-oriented programming.
1158 I recommend the book "LISP" by Winston and Horn and published by
1159 Addison Wesley for learning Lisp. The first edition of this book is
1160 based on MacLisp and the second edition is based on Common Lisp. XLISP
1161 will continue to migrate towards compatibility with Common Lisp.
1163 You will probably also need a copy of "Common Lisp: The Language" by
1164 Guy L. Steele, Jr., published by Digital Press to use as a reference for
1165 some of the Common Lisp functions that are described only briefly in
1166 this document.
1169 File: slisp, Node: Note From Author, Next: Xlisp Command Loop, Prev: Xlisp Tutorial Introduction, Up: Xlisp Tutorial
1171 A Note From The Author
1172 ======================
1174 If you have any problems with XLISP, feel free to contact me for
1175 help or advice. Please remember that since XLISP is available in
1176 source form in a high level language, many users have been making
1177 versions available on a variety of machines. If you call to report a
1178 problem with a specific version, I may not be able to help you if that
1179 version runs on a machine to which I don't have access. Please have
1180 the version number of the version that you are running readily
1181 accessible before calling me.
1183 If you find a bug in XLISP, first try to fix the bug yourself using
1184 the source code provided. If you are successful in fixing the bug,
1185 send the bug report along with the fix to me. If you don't have access
1186 to a C compiler or are unable to fix a bug, please send the bug report
1187 to me and I'll try to fix it.
1189 Any suggestions for improvements will be welcomed. Feel free to
1190 extend the language in whatever way suits your needs. However, PLEASE
1192 would like to be the clearing house for new features added to XLISP.
1193 If you want to add features for your own personal use, go ahead. But,
1194 if you want to distribute your enhanced version, contact me first.
1195 Please remember that the goal of XLISP is to provide a language to
1196 learn and experiment with LISP and object-oriented programming on small
1197 computers. I don't want it to get so big that it requires megabytes of
1198 memory to run.
1201 File: slisp, Node: Xlisp Command Loop, Next: Break Command Loop, Prev: Note From Author, Up: Xlisp Tutorial
1203 Xlisp Command Loop
1204 ==================
1206 When XLISP is started, it first tries to load the workspace
1207 "xlisp.wks" from the current directory. If that file doesn't exist,
1208 XLISP builds an initial workspace, empty except for the built-in
1209 functions and symbols.
1211 Then XLISP attempts to load "init.lsp" from the current directory.
1212 It then loads any files named as parameters on the command line (after
1213 appending ".lsp" to their names).
1215 XLISP then issues the following prompt:
1217 >
1219 This indicates that XLISP is waiting for an expression to be typed.
1221 When a complete expression has been entered, XLISP attempts to
1222 evaluate that expression. If the expression evaluates successfully,
1223 XLISP prints the result and then returns to the initial prompt waiting
1224 for another expression to be typed.

ViewVC Help
Powered by ViewVC 1.1.26