Scripts

A Scheme scriptis a top-level program (see report chapter on “Top-level programs”) which is packaged such that it is directly executable by conforming implementations of Scheme, on one or more plaforms.

C.1  Script interpreter

Where applicable, implementations should provide a script interpreter in the form of an executable program named scheme-script that is capable of initiating the execution of Scheme scripts, as described below.

Rationale:   Distributing a Scheme program that is portable with respect to both Scheme implementations and operating systems is challenging, even if that program has been written in standard Scheme. Languages with a single or primary implementation can at least rely on a standard name for their script interpreters. Standardizing the name of the executable used to start a Scheme script removes one barrier to the distribution of Scheme scripts.

C.2  Syntax

A Scheme script is a delimited piece of text, typically a file, with the following syntax:

<script> → <script header> <top-level program>
         | <top-level program>
<script header> → <shebang> /usr/bin/env <space>
         scheme-script <linefeed>
<shebang> → #! | #! <space>

C.2.1  Script header

The script header, if present on the first line of a script, is used by Unix-like operating systems to identify the interpreter to execute that script.

The script header syntax given above is the recommended portable form that programmers should use. However, if the first line of a script begins with #!/ or #!<space>, implementations should ignore it on all platforms, even if it does not conform to the recommended syntax.

Rationale:   Requiring script interpreters to recognize and ignore the script header helps ensure that Scheme scripts written for Unix-like systems can also run on other kinds of systems. Furthermore, recognizing all #!/ or #!<space> combinations allows local customizations to be performed by altering a script header from its default form.

C.2.2  Example

#!/usr/bin/env scheme-script
#!r6rs
(import (rnrs base (6))
        (rnrs io ports (6))
        (rnrs programs))
(put-bytes (standard-output-port)
           (call-with-port
               (open-file-input-port
                 (cadr (command-line)))
             get-bytes-all))

C.3  Platform considerations

Many platforms require that scripts be marked as executable in some way. The platform-specific details of this are beyond the scope of this report. Scripts that are not suitably marked as executable will fail to execute on many platforms. Other platform-specific notes for some popular operating systems follow.

C.3.1  Apple Mac OS X

The Mac OS X operating system supports the Unix-like script header for shell scripts that run in the Terminal. Depending on the intended usage, it may be advisable to choose a file name ending in .command for a script, as this makes the script double-clickable.

C.3.2  Unix

Scheme scripts on Unix-like operating systems are supported by the presence of the script header. Scripts that omit the script header are unlikely to be directly executable on Unix-like systems.

To support installation of the Scheme script interpreter in non-standard paths, scripts should use the /usr/bin/env program as specified in the recommended script header syntax. (Note that on many Unix-like systems, this also allows the script interpreter itself to be implemented as a shell script.)

C.3.3  Microsoft Windows

The Windows operating system allows a file extension to be associated with a script interpreter such as scheme-script. This association may be configured appropriately by Scheme implementations, installation programs, or by the user.

C.3.4  Selecting an implementation

If multiple implementations of Scheme are installed on a machine, the user may wish to specify which implementation should be used to execute Scheme scripts by default. Most platforms support some mechanism for choosing between alternative implementations of a program. For example, Debian GNU/Linux uses the /etc/alternatives mechanism to do this; Microsoft Windows uses file extension associations. Implementations are expected to configure this appropriately, e.g., as part of their installation procedure. Failing that, users must perform any necessary configuration to choose their preferred Scheme script interpreter.