suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

finish mzc docs

Browse Source 
svn: r9378
This commit is contained in:
Matthew Flatt 2008-04-20 14:28:20 +00:00
parent c8eb111e26
commit 476c374751
11 changed files with 304 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
collects/compiler/compiler-unit.ss
View File

@ -101,7 +101,10 @@
(make-unprefixed-compiler 'compile-c-extension))
(define (compile-to-zo src dest namespace eval?)
((if eval? (lambda (t) (t)) with-module-reading-parameterization)
((if eval?
(lambda (t) (parameterize ([read-accept-reader #t])
(t)))
with-module-reading-parameterization)
(lambda ()
(parameterize ([current-namespace namespace])
(compile-file src dest
@ -131,7 +134,7 @@
f)))
source-files))
(for ([f source-files] [b file-bases])
(let ([zo (append-zo-suffix b)])
(let ([zo (append-zo-suffix f)])
(compile-to-zo f zo n prefix)))))
(define (compile-directory dir info)
@ -158,7 +161,7 @@
(parameterize ([current-directory dir]
[current-load-relative-directory dir]
;; Verbose compilation manager:
[manager-trace-handler (lambda (s) (printf "~a\n" s))]
;; [manager-trace-handler (lambda (s) (printf "~a\n" s))]
[manager-compile-notify-handler
(lambda (path) ((compile-notify-handler) path))])
;; Compile the collection files via make-collection
@ -174,7 +177,8 @@
(when (info* 'compile-subcollections (lambda () #f))
(printf "Warning: ignoring `compile-subcollections' entry in info ~a\n"
dir))
(for ([p (directory-list dir)])
(for ([p (directory-list dir)]
#:when (directory-exists? (build-path dir p)))
(let ([s (path->string p)])
;; this is the same check that setup/setup-unit is doing in
;; `make-cc*'

206
collects/compiler/main.ss
View File

@ -82,7 +82,30 @@
[once-any
[("-k" "--make")
,(lambda (f) 'make-zo)
(("Recursively compile Scheme source(s); uses/generates .dep files" ""))]
("Recursively compile Scheme source(s); uses/generates .dep files")]
[("--make-collection")
,(lambda (f) 'collection-zos)
((,(format "Makes all Scheme sources in specified collection(s)") ""))]
[("--exe")
,(lambda (f name) (exe-output name) 'exe)
(,(format "Embed module in MzScheme to create <exe>")
"exe")]
[("--gui-exe")
,(lambda (f name) (exe-output name) 'gui-exe)
(,(format "Embed module in MrEd to create <exe>")
"exe")]
[("--exe-dir")
,(lambda (f name) (exe-dir-output name) 'exe-dir)
((,(format "Combine executables with support files in <dir>") "")
"dir")]
[("--collection-plt")
,(lambda (f name) (plt-output name) 'plt-collect)
(,(format "Create .plt <archive> containing collections")
"archive")]
[("--plt")
,(lambda (f name) (plt-output name) 'plt)
((,(format "Create .plt <archive> containing relative files/dirs") "")
"archive")]
[("--cc")
,(lambda (f) 'cc)
(,(format "Compile arbitrary file(s) for an extension: ~a -> ~a"
@ -100,46 +123,22 @@
(extract-suffix append-c-suffix)
(extract-suffix append-c-suffix))
""))]
[("--exe")
,(lambda (f name) (exe-output name) 'exe)
(,(format "Embed module in MzScheme to create <exe>")
"exe")]
[("--gui-exe")
,(lambda (f name) (exe-output name) 'gui-exe)
(,(format "Embed module in MrEd to create <exe>")
"exe")]
[("--exe-dir")
,(lambda (f name) (exe-dir-output name) 'exe-dir)
((,(format "Combine executables with support files in <dir>") "")
"dir")]
[("--c-mods")
,(lambda (f name) (mods-output name) 'c-mods)
((,(format "Write C-embeddable module bytecode to <file>") "")
"file")]
[("--collection-plt")
,(lambda (f name) (plt-output name) 'plt-collect)
(,(format "Create .plt <archive> containing collections")
"archive")]
[("--plt")
,(lambda (f name) (plt-output name) 'plt)
((,(format "Create .plt <archive> containing relative files/dirs") "")
"archive")]
[("--expand")
,(lambda (f) 'expand)
((,(format "Write macro-expanded Scheme source(s) to stdout") ""))]
[("-z" "--zo")
,(lambda (f) 'zo)
((,(format "Output ~a file(s) from Scheme source(s)" (extract-suffix append-zo-suffix)) ""))]
[("-e" "--extension")
,(lambda (f) 'compile)
(,(format "Output ~a file(s) from Scheme source(s)" (extract-suffix append-extension-suffix)))]
[("-c" "--c-source")
,(lambda (f) 'compile-c)
((,(format "Output ~a file(s) from Scheme source(s)" (extract-suffix append-c-suffix))
""))]
[("-z" "--zo")
,(lambda (f) 'zo)
(,(format "Output ~a file(s) from Scheme source(s)" (extract-suffix append-zo-suffix)))]
[("--collection-zos")
,(lambda (f) 'collection-zos)
((,(format "Compile specified collection to ~a files" (extract-suffix append-zo-suffix)) ""))]
[("--expand")
,(lambda (f) 'expand)
(,(format "Write macro-expanded Scheme source(s) to stdout"))]]
(,(format "Output ~a file(s) from Scheme source(s)" (extract-suffix append-c-suffix)))]]
[help-labels ""]
[once-any
[("--3m")
@ -175,6 +174,74 @@
(,(format "Output -z to \"compiled\", -e to ~s"
(path->string (build-path "compiled" "native"
(system-library-subpath #f)))))]]
[help-labels
"--------------------- executable configuration flags ------------------------"]
[once-each
[("--collects-path")
,(lambda (f i)
(exe-embedded-collects-path i))
("Set <path> main collects in --[gui-]exe/--exe-dir" "path")]
[("--collects-dest")
,(lambda (f i) (exe-embedded-collects-dest i))
("Add --[gui-]exe collection code to <dir>" "dir")]
[("--ico")
,(lambda (f i) (exe-aux (cons (cons 'ico i) (exe-aux))))
("Windows icon for --[gui-]exe executable" ".ico-file")]
[("--icns")
,(lambda (f i) (exe-aux (cons (cons 'icns i) (exe-aux))))
("Mac OS X icon for --[gui-]exe executable" ".icns-file")]
[("--orig-exe")
,(lambda (f) (exe-aux (cons (cons 'original-exe? #t) (exe-aux))))
("Use original executable for --[gui-]exe instead of stub")]]
[multi
[("++lib")
,(lambda (f l)
(exe-embedded-libraries (append (exe-embedded-libraries) (list l))))
("Embed <lib> in --[gui-]exe executable or --c-mods output" "lib")]
[("++collects-copy")
,(lambda (f d)
(exe-dir-add-collects-dirs (append (exe-dir-add-collects-dirs) (list d))))
("Add collects in <dir> to --exe-dir" "dir")]
[("++exf")
,(add-to-param exe-embedded-flags)
("Add flag to embed in --[gui-]exe executable" "flag")]
[("--exf")
,(lambda (f v) (exe-embedded-flags (remove v (exe-embedded-flags))))
("Remove flag to embed in --[gui-]exe executable" "flag")]
[("--exf-clear")
,(lambda (f) (exe-embedded-flags null))
("Clear flags to embed in --[gui-]exe executable")]
[("--exf-show")
,(lambda (f) (printf "Flags to embed: ~s\n" (exe-embedded-flags)))
("Show flag to embed in --[gui-]exe executable")]]
[help-labels
"----------------------------- .plt archive flags ----------------------------"]
[once-each
[("--plt-name")
,(lambda (f n) (plt-name n))
("Set the printed <name> describing the archive" "name")]
[("--replace")
,(lambda (f) (plt-files-replace #t))
("Files in archive replace existing files when unpacked")]
[("--at-plt")
,(lambda (f) (plt-files-plt-relative? #t))
("Files/dirs in archive are relative to user's add-ons directory")]]
[once-any
[("--all-users")
,(lambda (f) (plt-files-plt-home-relative? #t))
("Files/dirs in archive go to PLT installation if writable")]
[("--force-all-users")
,(lambda (f) (plt-files-plt-home-relative? #t) (plt-force-install-dir? #t))
("Files/dirs forced to PLT installation")]]
[once-each
[("--include-compiled")
,(lambda (f) (plt-include-compiled #t))
("Include \"compiled\" subdirectories in the archive")]]
[multi
[("++setup")
,(lambda (f c)
(plt-setup-collections (append (plt-setup-collections) (list c))))
("Setup <collect> after the archive is unpacked" "collect")]]
[help-labels
"------------------- compiler/linker configuration flags ---------------------"]
[once-each
@ -256,75 +323,7 @@
(expand-for-link-variant (current-extension-preprocess-flags))))
("Show C preprocess (xform) flags")]]
[help-labels
"--------------------- executable configuration flags ------------------------"]
[once-each
[("--collects-path")
,(lambda (f i)
(exe-embedded-collects-path i))
("Set <path> main collects in --[gui-]exe/--exe-dir" "path")]
[("--collects-dest")
,(lambda (f i) (exe-embedded-collects-dest i))
("Add --[gui-]exe collection code to <dir>" "dir")]
[("--ico")
,(lambda (f i) (exe-aux (cons (cons 'ico i) (exe-aux))))
("Windows icon for --[gui-]exe executable" ".ico-file")]
[("--icns")
,(lambda (f i) (exe-aux (cons (cons 'icns i) (exe-aux))))
("Mac OS X icon for --[gui-]exe executable" ".icns-file")]
[("--orig-exe")
,(lambda (f) (exe-aux (cons (cons 'original-exe? #t) (exe-aux))))
("Use original executable for --[gui-]exe instead of stub")]]
[multi
[("++lib")
,(lambda (f l)
(exe-embedded-libraries (append (exe-embedded-libraries) (list l))))
("Embed <lib> in --[gui-]exe executable" "lib")]
[("++collects-copy")
,(lambda (f d)
(exe-dir-add-collects-dirs (append (exe-dir-add-collects-dirs) (list d))))
("Add collects in <dir> to --exe-dir" "dir")]
[("++exf")
,(add-to-param exe-embedded-flags)
("Add flag to embed in --[gui-]exe executable" "flag")]
[("--exf")
,(lambda (f v) (exe-embedded-flags (remove v (exe-embedded-flags))))
("Remove flag to embed in --[gui-]exe executable" "flag")]
[("--exf-clear")
,(lambda (f) (exe-embedded-flags null))
("Clear flags to embed in --[gui-]exe executable")]
[("--exf-show")
,(lambda (f) (printf "Flags to embed: ~s\n" (exe-embedded-flags)))
("Show flag to embed in --[gui-]exe executable")]]
[help-labels
"----------------------------- .plt archive flags ----------------------------"]
[once-each
[("--plt-name")
,(lambda (f n) (plt-name n))
("Set the printed <name> describing the archive" "name")]
[("--replace")
,(lambda (f) (plt-files-replace #t))
("Files in archive replace existing files when unpacked")]
[("--at-plt")
,(lambda (f) (plt-files-plt-relative? #t))
("Files/dirs in archive are relative to user's add-ons directory")]]
[once-any
[("--all-users")
,(lambda (f) (plt-files-plt-home-relative? #t))
("Files/dirs in archive go to PLT installation if writable")]
[("--force-all-users")
,(lambda (f) (plt-files-plt-home-relative? #t) (plt-force-install-dir? #t))
("Files/dirs forced to PLT installation")]]
[once-each
[("--include-compiled")
,(lambda (f) (plt-include-compiled #t))
("Include \"compiled\" subdirectories in the archive")]]
[multi
[("++setup")
,(lambda (f c)
(plt-setup-collections (append (plt-setup-collections) (list c))))
("Setup <collect> after the archive is unpacked" "collect")]]
[help-labels
"----------------------- compiler optimization flags -------------------------"]
"-------------------- -c/-e compiler optimization flags ----------------------"]
[once-each
[("--no-prop")
,(lambda (f) (compiler:option:propagate-constants #f))
@ -469,7 +468,10 @@
(if did-one? "output to" "already up-to-date at")
dest))))))]
[(collection-zos)
(apply compile-collection-zos source-files)]
(parameterize ([compile-notify-handler
(lambda (path)
(printf " making ~s\n" (path->string path)))])
(apply compile-collection-zos source-files))]
[(cc)
(for ([file source-files])
(let* ([base (extract-base-filename/c file 'mzc)]

4
collects/scribblings/inside/overview.scrbl
View File

@ -1,7 +1,7 @@
#lang scribble/doc
@(require "utils.ss")
@title{Overview}
@title[#:tag "overview"]{Overview}
@section{CGC versus 3m}
@ -223,7 +223,7 @@ which case the @DFlag{xform} step should be skipped.
@; ----------------------------------------------------------------------
@section{Embedding MzScheme into a Program}
@section[#:tag "embedding"]{Embedding MzScheme into a Program}
@section-index["embedding MzScheme"]

17
collects/scribblings/mzc/c-mods.scrbl Normal file
View File

@ -0,0 +1,17 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@title[#:tag "c-mods"]{Embedding Scheme Modules via C}
The @DFlag{c-mods} mode for @|mzc| takes a set of Scheme modules and
generates a C source file that can be used as part of program that
embeds the PLT Scheme run-time system. See @secref[#:doc inside-doc
"embedding"] in @other-manual[inside-doc] for an explanation of
embedding programs.
The generated source file embeds the specified modules, and it defines
a @tt{declare_modules} function that puts the module declarations
into a namespace. Thus, using the output of @exec{mzc --c-mods}, a
program can embed PLT Scheme with a set of modules so that it does not
need a @filepath{collects} directory to load modules at run time.

52
collects/scribblings/mzc/cc.scrbl
View File

@ -1,5 +1,57 @@
#lang scribble/doc
@(require scribble/manual
(for-label scheme/base)
"common.ss")
@(define (xflag str) (as-index (DFlag str)))
@(define (pxflag str) (as-index (DPFlag str)))
@title[#:tag "cc"]{Compiling and Linking C Extensions}
A @deftech{dynamic extension} is a shared library (a.k.a. DLL) that
extends PLT Scheme using the C API. An extension can be loaded
explicitly via @scheme[load-extension], or it can be loaded implicitly
through @scheme[require] or @scheme[load/use-compiled] in place of a
source @scheme[_file] when the extension is located at
@schemeblock[
(build-path "compiled" "native" (system-library-subpath)
(path-add-suffix _file (system-type 'so-suffix)))
]
relative to @scheme[_file].
For information on writing extensions, see @other-manual[inside-doc].
Three @|mzc| modes help for building extensions:
@itemize[
@item{@DFlag{cc} : Runs the host system's C compiler, automatically
supplying flags to locate the PLT Scheme header files and to
compile for inclusion in a shared library.}
@item{@DFlag{ld} : Runs the host system's C linker, automatically
supplying flags to locate and link to the PLT Scheme libraries
and to generate a shared library.}
@item{@DFlag{xform} : Transforms C code that is written without
explicit GC-cooperation hooks to cooperate with PLT Scheme's 3m
garbage collector; see @secref[#:doc inside-doc "overview"] in
@other-manual[inside-doc].}
]
Compilation and linking build on the @schememodname[dynext/compile]
and @schememodname[dynext/link] libraries. The following @|mzc| flags
correspond to setting or accessing parameters for those libraries: @xflag{tool},
@xflag{compiler}, @xflag{ccf}, @xflag{ccf}, @xflag{ccf-clear},
@xflag{ccf-show}, @xflag{linker}, @pxflag{ldf}, @xflag{ldf},
@xflag{ldf-clear}, @xflag{ldf-show}, @pxflag{ldl}, @xflag{ldl-show},
@pxflag{cppf}, @pxflag{cppf} @pxflag{cppf-clear}, and @xflag{cppf-show}.
The @as-index{@DFlag{3m}} flag specifies that the extension is to be
loaded into the 3m variant of PLT Scheme. The @as-index{@DFlag{cgc}}
flag specifies that the extension is to be used with the CGC. The
default depends on @|mzc|: @DFlag{3m} if @|mzc| itself is running in
3m, @DFlag{cgc} if @|mzc| itself is running in CGC.

5
collects/scribblings/mzc/common.ss
View File

@ -1,7 +1,10 @@
#lang scheme/base
(require scribble/manual)
(provide mzc)
(provide mzc
inside-doc)
(define mzc (exec "mzc"))
(define inside-doc
'(lib "scribblings/inside/inside.scrbl"))

33
collects/scribblings/mzc/ext.scrbl
View File

@ -3,3 +3,36 @@
"common.ss")
@title[#:tag "ext"]{Compiling to Native Code via C}
The @DFlag{extension}/@Flag{e} mode for @|mzc| is similar to the
@DFlag{zo} mode, except that the compiled form of the module is a
native-code shared library instead of bytecode. Native code is
generated with the help of the host system's C compiler. This mode is
rarely useful, because the just-in-time (JIT) compiler that is built
into PLT Scheme provides better performance with lower overhead on the
platforms where it is supported (see @secref[#:doc '(lib
"scribblings/guide/guide.scrbl") "performance"]).
As with @DFlag{zo} mode, the generated shared library by default is
placed in the same directory as the source file---which is not where
it will be found automatically when loading the source. Use the
@as-index{@DFlag{auto-dir}} flag to redirect the output to a
@scheme[(build-path "compiled" "native" (system-library-subpath))]
subdirectory, where it will be found automatically when loading the
source file.
The @DFlag{--c-source}/@Flag{c} mode for @|mzc| is like the
@DFlag{extension}/@Flag{e} mode, except that compilation stops with
the generation of C code.
All of the C compiler and linker flags that apply to @DFlag{cc} and
@DFlag{ld} mode also apply to @DFlag{extension} mode; see
@secref["cc"]. In addition, a few flag provide some control over the
Scheme-to-C compiler: @as-index{@DFlag{no-prop}},
@as-index{@DFlag{inline}}, @as-index{@DFlag{prim}},
@as-index{@DFlag{stupid}},
@as-index{@DFlag{unsafe-disable-interrupts}},
@as-index{@DFlag{unsafe-skip-tests}}, and
@as-index{@DFlag{unsafe-fixnum-arithmetic}}. Use @exec{mzc --help} for
an explanation of each flag.

37
collects/scribblings/mzc/mzc.scrbl
View File

@ -18,17 +18,11 @@ command-line flags:
@itemize{
@item{@as-index{@DFlag{make}} or @as-index{@Flag{k}} (the default) :
@item{@as-index{@DFlag{make}} (the default), @as-index{@Flag{k}}
or @as-index{@DFlag{make-collection}} :
Compiles Scheme modules and all transitive imports to
bytecode. See @secref["make"].}
@item{@as-index{@DFlag{cc}}, @as-index{@DFlag{ld}},
@as-index{@DFlag{xform}} or @as-index{@Flag{x}} : Compiles,
links or transforms (for GC cooperation) C code to extend the
PLT Scheme runtime system. See @secref["cc"]. Using the
@scheme[scheme/foreign] FFI is often better; see
@other-manual['(lib "scribblings/foreign/foreign.scrbl")].}
@item{@as-index{@DFlag{exe}}, @as-index{@DFlag{gui-exe}}, or
@as-index{@DFlag{exe-dir}} : Creates an executable to run a
Scheme module, or assembles all support libraries to move an
@ -39,24 +33,39 @@ command-line flags:
Scheme installation. See @secref["plt"]. @|PLaneT| is usually a
better alternative.}
@item{@as-index{@DFlag{extension}}, @as-index{@Flag{e}},
@as-index{@DFlag{c-source}}, or @as-index{@Flag{c}} : Compiles
Scheme code to a native-code extension via C. See
@secref["ext"]. @|rare|}
@item{@as-index{@DFlag{cc}}, @as-index{@DFlag{ld}},
@as-index{@DFlag{xform}} or @as-index{@Flag{x}} : Compiles,
links or transforms (for GC cooperation) C code to extend the
PLT Scheme runtime system. See @secref["cc"]. Using the
@scheme[scheme/foreign] FFI is often better; see
@other-manual['(lib "scribblings/foreign/foreign.scrbl")].}
@item{@as-index{@DFlag{c-mods}} : Creates C source to embed Scheme
modules into an executable that also embeds PLT Scheme. See
@secref["c-mods"].}
@item{@as-index{@DFlag{expand}} : Pretty-prints the macro-expanded
form of a Scheme program.}
@item{@as-index{@DFlag{zo}}, @as-index{@Flag{z}}, or
@as-index{@DFlag{collection-zo}} : Compiles Scheme code to
bytecode, without following transitive imports. See
@secref["zo"]. @|rare|}
@item{@as-index{@DFlag{extension}}, @as-index{@Flag{e}},
@as-index{@DFlag{c-source}}, or @as-index{@Flag{c}} : Compiles
Scheme code to a native-code extension via C. See
@secref["ext"]. @|rare|}
}
@include-section["make.scrbl"]
@include-section["cc.scrbl"]
@include-section["sa.scrbl"]
@include-section["plt.scrbl"]
@include-section["ext.scrbl"]
@include-section["cc.scrbl"]
@include-section["c-mods.scrbl"]
@include-section["zo.scrbl"]
@include-section["ext.scrbl"]
@include-section["api.scrbl"]
@index-section[]

10
collects/scribblings/mzc/plt.scrbl
View File

@ -93,7 +93,7 @@ collection:
When packing collections, @|mzc| checks the following fields of each
collection's @filepath{info.ss} file (see @secref["info.ss" #:doc
'(lib "scribblings/reference/reference.scrbl")]):
'(lib "scribblings/setup-plt/setup-plt.scrbl")]):
@itemize{
@ -135,6 +135,12 @@ unpacked, the unpacker will check that the MrEd collection is
installed (not just MzScheme), and that MrEd has the same version as
when @filepath{sirmail.plt} was created.
@; ----------------------------------------
@section{Scheme API for Packaging}
Although @|mzc|'s command-line interface is sufficient for most
purposes, the @schememodname[setup/pack] library provides a more
purposes, see the @schememodname[setup/pack] library for a more
general interface for constructing archives.

52
collects/scribblings/mzc/zo.scrbl
View File

@ -1,8 +1,58 @@
#lang scribble/doc
@(require scribble/manual
(for-label scheme/base
scheme/class
scheme/unit)
"common.ss")
@title[#:tag "zo"]{Compiling to Raw Bytecode}
The @DFlag{zo}/@Flag{z} mode for @|mzc| is an improverished form of
the default @DFlag{make}/@Flag{k} mode described in @secref["make"].
the default @DFlag{make}/@Flag{k} mode (which is described in
@secref["make"]), because it does not track import dependencies. It
does, however, support compilation of non-module source.
By default, the generated bytecode is placed in the same directory as
the source file---which is not where it will be found automatically
when loading the source. Use the @as-index{@DFlag{auto-dir}} flag to
redirect the output to a @filepath{compiled} subdirectory, where it
will be found automatically when loading the source file.
Outside of a module, top-level @scheme[define-syntaxes],
@scheme[module], @scheme[#%require],
@scheme[define-values-for-syntaxes], and and @scheme[begin]
expressions are handled specially by @exec{mzc --zo}: the compile-time
portion of the expression is evaluated, because it might affect later
expressions. (The @Flag{m} or @DFlag{module} flag turns off this
special handling.)
For example, when compiling the file containing
@schemeblock[
(require scheme/class)
(define f (class% object% (super-new)))
]
the @scheme[class] form from the @schememodname[scheme/class] library
must be bound in the compilation namespace at compile time. Thus, the
@scheme[require] expression is both compiled (to appear in the output
code) and evaluated (for further computation).
Many definition forms expand to @scheme[define-syntaxes]. For example,
@scheme[define-signature] expands to @scheme[define-syntaxes]. In
@scheme[--zo] mode, @|mzc| detects @scheme[define-syntaxes] and other
expressions after expansion, so top-level @scheme[define-signature]
expressions affect the compilation of later expressions, as a
programmer would expect.
In contrast, a @scheme[load] or @scheme[eval] expression in a source
file is compiled---but @emph{not evaluated!}---as the source file is
compiled. Even if the @scheme[load] expression loads syntax or
signature definitions, these will not be loaded as the file is
compiled. The same is true of application expressions that affect the
reader, such as @scheme[(read-case-sensitive #t)]. The @Flag{p} or
@DFlag{prefix} flag for @|mzc| takes a file and loads it before
compiling the source files specified on the command line.
In general, a better solution is to put all code to compile into a
module and use @|mzc| in its default mode.

4
collects/scribblings/reference/pairs.scrbl
View File

@ -531,8 +531,8 @@ must merely start with a chain of at least @scheme[pos] pairs.
@defproc[(add-between [lst list?] [v any/c]) list?]{
Returns a list that is made of items from @scheme[lst], with
@scheme[v] between each two items.
Returns a list with the same elements as @scheme[lst], but with
@scheme[v] between each pair of items in @scheme[lst].
@examples[#:eval list-eval
(add-between '(x y z) 'or)