The trivial-dump-core Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The trivial-dump-core Reference Manual

This is the trivial-dump-core Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:41:21 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

trivial-dump-core is an MIT-licensed wrapper that provides a common
interface between lisp implementations for the creation of lisp image
files and executables.

Currently trivial-dump-core supports SBCL, Clozure CL and CLISP.

* Installation

  trivial-dump-core is available via [[http://www.quicklisp.org/beta/][quicklisp]]:

#+BEGIN_SRC lisp
  (ql:quickload "trivial-dump-core")
#+END_SRC

  The source repository is at https://github.com/rolando2424/trivial-dump-core

* Library functions

  There are three main functions in trivial-dump-core:

  * dump-image
  
  * dump-image-init

  * save-executable

** dump-image

   The =dump-image= function is used to freeze the state of your Lisp
   session and store it in an "image file." You can then, at a later
   time, load that image file back into your Lisp implementation.

   The =dump-image= function takes the path of the image file as its
   only argument.

** save-executable

   The =save-executable= function creates an executable file that
   includes the Lisp image (you can distribute it as-is without
   needing to install the Lisp implementation on the target
   machine). Some implementations (Clozure, SBCL) will exit after this
   function is called.

   The =save-executable= function takes 3 arguments:

   * =filename= - Path of the executable file

   * =init-function= - Zero-argument function object that acts as the
     entry point to your executable (the equivalent of main() in C).

** dump-image-init
   
   Almost the same as dump-image, but takes and init-function argument, like save-executable.

* Examples

** dump-image

   Let's open up, for example, Clozure CL:

#+BEGIN_SRC
   rolando@rolando-desktop:~$ ccl
   Welcome to Clozure Common Lisp Version 1.7-r14925M  (LinuxX8632)!
   ?
#+END_SRC

   Now we load trivial-dump-core (we assume you have quicklisp
   installed already).

#+BEGIN_SRC
   ? (ql:quickload "trivial-dump-core")
   To load "trivial-dump-core":
     Load 1 ASDF system:
       trivial-dump-core
   ; Loading "trivial-dump-core"
   [package trivial-dump-core]
   (TRIVIAL-DUMP-CORE)
   ?
#+END_SRC

   Let's define a new function:

#+BEGIN_SRC lisp
   ? (defun hello-world ()
       (format t "Hello, World!"))
   HELLO-WORLD
   ?
#+END_SRC

   So now this lisp interpreter has a function called
   =hello-world=. Let's save dump the interpreter state to a file
   called "my-core.ccl":

#+BEGIN_SRC
   ? (trivial-dump-core:dump-image "my-core.ccl")
   To run the image, use the following command in the terminal:
   ccl -I my-core.ccl
   rolando@rolando-desktop:~$
#+END_SRC

   You'll notice that we're back in the command-line. This behaviour
   is implementation-dependent. For example, in CLISP you stay in the
   REPL even after creating an image.

   Also notice the command =ccl -I my-core.ccl= appeared. That's the command
   you have to type in the command-line to make ccl open the image you
   just created. Even though the specific flags you need to use change
   from implementation to implementation, trivial-dump-core will
   always show you the command you need to use to open back the image.

   So let's open it.

#+BEGIN_SRC
   rolando@rolando-desktop:~$ ccl -I my-core.ccl
   Welcome to Clozure Common Lisp Version 1.7-r14925M  (LinuxX8632)!
   ?
#+END_SRC

   So far, everything is the same as usual right? However, before
   creating this image, we defined a new function called
   =hello-world=. This function should still exist, even though we
   closed the lisp interpreter.

#+BEGIN_SRC lisp
   ? (hello-world)
   Hello, World!
   NIL
   ?
#+END_SRC

   As you can see, the function still exists.

   Currently, you can use the =dump-image= function in SBCL, CLISP and
   Clozure CL.

   Keep in mind that you can't open an image using a implementation
   that's different from the one that created it, ie. you can't create
   an image in SBCL and then open it in CLISP.

** save-executable
   This time, let's open up SBCL.

#+BEGIN_SRC
   rolando@rolando-desktop:~$ sbcl
   This is SBCL 1.0.55, an implementation of ANSI Common Lisp.
   More information about SBCL is available at .

   SBCL is free software, provided as is, with absolutely no warranty.
   It is mostly in the public domain; some portions are provided under
   BSD-style licenses.  See the CREDITS and COPYING files in the
   distribution for more information.
   *
#+END_SRC

   As before, we'll need to load trivial-dump-core using quicklisp.

#+BEGIN_SRC
   * (ql:quickload 'trivial-dump-core)
   To load "trivial-dump-core":
     Load 1 ASDF system:
       trivial-dump-core
   ; Loading "trivial-dump-core"
   [package trivial-dump-core]
   (TRIVIAL-DUMP-CORE)
   *
#+END_SRC

   Let's define a new function.

#+BEGIN_SRC
   * (defun hello-world ()
       (format t "Hello, World!~%"))

   HELLO-WORLD
   *
#+END_SRC

   Finally, we create an executable with the name "sbcl-hello-world"
   using the =save-executable= function, using the =hello-world= has
   the entry point.

#+BEGIN_SRC
   * (trivial-dump-core:save-executable "sbcl-hello-world" #'hello-world)
   [undoing binding stack and other enclosing state... done]
   [saving current Lisp image into sbcl-hello-world:
   writing 3512 bytes from the read-only space at 0x01000000
   writing 2224 bytes from the static space at 0x01100000
   writing 32231424 bytes from the dynamic space at 0x09000000
   done]
   rolando@rolando-desktop:~$
#+END_SRC

   As it already happened with Clozure CL during the =dump-image=
   example, what happens after you call =save-executable= is
   implementation-dependent. In this case, the lisp interpreter closed
   and we are back in the command-line.

   However, there's now a new executable file in the folder. Let's run
   it.

#+BEGIN_SRC
   rolando@rolando-desktop:~$ ./sbcl-hello-world
   Hello, World!
   rolando@rolando-desktop:~$
#+END_SRC

* SBCL and Slime

  There a problem with saving core images in SBCL when it's running
  more than one thread, as is the case with the SBCL+Slime
  combination.

  So to use trivial-dump-core with SBCL running with a Slime prompt,
  the process is a little different.

  You call the functions =dump-image= and =save-executable= as usual,
  but those functions instead of working the normal way, they print
  out a sexp that you need to evaluate in the =*inferior-lisp*= buffer.

** Example

   Inside emacs press =C-u M-x slime RET sbcl RET=.

   When the prompt opens, load trivial-dump-core as normal.

#+BEGIN_SRC
   CL-USER> (ql:quickload 'trivial-dump-core)
   To load "trivial-dump-core":
     Load 1 ASDF system:
       trivial-dump-core
   ; Loading "trivial-dump-core"

   (TRIVIAL-DUMP-CORE)
   CL-USER>
#+END_SRC

   Let's create a new image using =dump-image=.

#+BEGIN_SRC
   CL-USER> (trivial-dump-core:dump-image "sbcl-slime")
   Cannot dump an sbcl image from inside Slime.

   Please go to the *inferior-lisp* buffer in emacs and run the following code:

   (trivial-dump-core::sbcl-dump-image-slime "sbcl-slime")
   NIL
   CL-USER>
#+END_SRC

   Notice the sexp in the message. Copy it into emacs' kill-ring and
   open the =*inferior-lisp*= buffer using =C-x b *inferior-lisp* RET=
   and paste the sexp there.

#+BEGIN_SRC
   * (trivial-dump-core::sbcl-dump-image-slime "sbcl-slime")
   ;; swank:close-connection: NIL
   To run the image, use the following command in the terminal:
   sbcl --core sbcl-slime
   [undoing binding stack and other enclosing state... done]
   [saving current Lisp image into sbcl-slime:
   writing 3512 bytes from the read-only space at 0x01000000
   writing 2224 bytes from the static space at 0x01100000
   writing 35590144 bytes from the dynamic space at 0x09000000
   done]

   Process inferior-lisp finished
#+END_SRC

   The end result is a core file similar to one created in the
   command-line.

   The same thing happens when you try to use =save-executable= with
   SBCL in Slime.

#+BEGIN_SRC
   CL-USER> (ql:quickload 'trivial-dump-core)
   To load "trivial-dump-core":
     Load 1 ASDF system:
       trivial-dump-core
   ; Loading "trivial-dump-core"

   (TRIVIAL-DUMP-CORE)
   CL-USER> (trivial-dump-core:save-executable "sbcl-exec-slime" #'(lambda () (format t "Hello, World!")))
   Cannot run save an sbcl image from inside Slime.

   Please go to the *inferior-lisp* buffer in emacs and run the following code:

   (trivial-dump-core::sbcl-save-slime-and-die "sbcl-exec-slime" #'(LAMBDA ()
                                                                     (FORMAT
                                                                      T
                                                                      "Hello, World!")))
   NIL
   CL-USER>
#+END_SRC

   Copy and paste the form into the =*inferior-lisp*= buffer to create
   an executable.

#+BEGIN_SRC
   * (trivial-dump-core::sbcl-save-slime-and-die "sbcl-exec-slime" #'(LAMBDA ()
                                                                     (FORMAT
                                                                      T
                                                                      "Hello, World!")))
   ;; swank:close-connection: NIL
   [undoing binding stack and other enclosing state... done]
   [saving current Lisp image into sbcl-exec-slime:
   writing 3512 bytes from the read-only space at 0x01000000
   writing 2224 bytes from the static space at 0x01100000
   writing 35340288 bytes from the dynamic space at 0x09000000
   done]

   Process inferior-lisp finished
#+END_SRC


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 trivial-dump-core

Author

Rolando Pereira <rolando_pereira_2@hotmail.com>

License

MIT License

Description

trivial-dump-core: Wrapper that allows the saving of the current lisp image as a "core" or as an "executable" across implementations.

Source

trivial-dump-core.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 trivial-dump-core.asd

Location

trivial-dump-core.asd

Systems

trivial-dump-core (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 trivial-dump-core/package.lisp

Parent

trivial-dump-core (system)

Location

package.lisp

Packages

trivial-dump-core


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 trivial-dump-core/trivial-dump-core.lisp

Dependency

package.lisp (file)

Parent

trivial-dump-core (system)

Location

trivial-dump-core.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 trivial-dump-core

Source

package.lisp (file)

Nicknames
Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: save-executable FILENAME INIT-FUNCTION

Make a stand-alone executable file from the current Lisp process.

FILENAME: Path of the executable file

INIT-FUNCTION: Zero-argument function object that acts as the entry point to your executable (the equivalent of main() in C).

Some implementations (Clozure, SBCL) will quit after this function is called.

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: dump-image FILENAME

Dump the current state of the Lisp process to an image file.

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)

Function: dump-image-init FILENAME INIT-FUNCTION

Dump the current state of the Lisp process to an image file, with an init function.

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: %save-executable-sbcl FILENAME INIT-FUNCTION
Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)

Macro: print-save-slime-and-die-help FILENAME INIT-FUNCTION

Print on the screen the command the user needs to run on the *inferior-lisp* buffer to save this image. This macro is only called when trying to save a sbcl lisp image inside slime.

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: is-slime-running ()

Return T if slime is running in the lisp image, otherwise return NIL.

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)

Function: print-dump-image-slime-help FILENAME

Print on the screen the command the user needs to run on the *inferior-lisp* buffer to dump this image. This macro is only called when trying to dump a sbcl lisp image inside slime.

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)

Function: sbcl-dump-image-slime FILENAME

Save a sbcl image, even when running from inside Slime.

This function should only be used in the *inferior-buffer* buffer, inside emacs.

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)

Function: sbcl-save-slime-and-die FILENAME INIT-FUNCTION

Save a sbcl image, even when running from inside Slime.

This function should only be used in the *inferior-buffer* buffer, inside emacs.

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)

Function: string-to-symbol STRING

Convert a string to a symbol

Package

trivial-dump-core

Source

trivial-dump-core.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, trivial-dump-core.asd: The trivial-dump-core<dot>asd file
File, Lisp, trivial-dump-core/package.lisp: The trivial-dump-core/package<dot>lisp file
File, Lisp, trivial-dump-core/trivial-dump-core.lisp: The trivial-dump-core/trivial-dump-core<dot>lisp file

L
Lisp File, trivial-dump-core.asd: The trivial-dump-core<dot>asd file
Lisp File, trivial-dump-core/package.lisp: The trivial-dump-core/package<dot>lisp file
Lisp File, trivial-dump-core/trivial-dump-core.lisp: The trivial-dump-core/trivial-dump-core<dot>lisp file

T
trivial-dump-core.asd: The trivial-dump-core<dot>asd file
trivial-dump-core/package.lisp: The trivial-dump-core/package<dot>lisp file
trivial-dump-core/trivial-dump-core.lisp: The trivial-dump-core/trivial-dump-core<dot>lisp file

Jump to:   F   L   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %  
D   F   I   M   P   S  
Index Entry  Section

%
%save-executable-sbcl: Internal macros

D
dump-image: Exported functions
dump-image-init: Exported functions

F
Function, dump-image: Exported functions
Function, dump-image-init: Exported functions
Function, is-slime-running: Internal functions
Function, print-dump-image-slime-help: Internal functions
Function, sbcl-dump-image-slime: Internal functions
Function, sbcl-save-slime-and-die: Internal functions
Function, string-to-symbol: Internal functions

I
is-slime-running: Internal functions

M
Macro, %save-executable-sbcl: Internal macros
Macro, print-save-slime-and-die-help: Internal macros
Macro, save-executable: Exported macros

P
print-dump-image-slime-help: Internal functions
print-save-slime-and-die-help: Internal macros

S
save-executable: Exported macros
sbcl-dump-image-slime: Internal functions
sbcl-save-slime-and-die: Internal functions
string-to-symbol: Internal functions

Jump to:   %  
D   F   I   M   P   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S   T  
Index Entry  Section

P
Package, trivial-dump-core: The trivial-dump-core package

S
System, trivial-dump-core: The trivial-dump-core system

T
trivial-dump-core: The trivial-dump-core system
trivial-dump-core: The trivial-dump-core package

Jump to:   P   S   T