Clone
clone: git://tcp80.org/grobe0ba/zuo gits://tcp80.org/grobe0ba/zuo
push: hjgit://tcp80.org/grobe0ba/zuo
patches to: grobe0ba@tcp80.org
Last commit
be919211
– grobe0ba <grobe0ba@tcp80.org>
authored
on 2024/06/20 15:38
rewrite mkfile
About
This is a mirror of the Zuo sources in the `racket/src/zuo` directory of
[the Racket repository](https://github.com/racket/racket).
Zuo: A Tiny Racket for Scripting
================================
You should use Racket to write scripts. But what if you need something
much smaller than Racket for some reason — or what if you're trying
to script a build of Racket itself? Zuo is a tiny Racket with
primitives for dealing with files and running processes, and it comes
with a `make`-like embedded DSL.
Zuo is a Racket variant in the sense that program files start with
`#lang`, and the module path after `#lang` determines the parsing and
expansion of the file content. That's how the `make`-like DSL is
defined, and even the base Zuo language is defined by layers of
`#lang`s. One of the early layers implements macros.
Some Example Scripts
--------------------
See [`local/hello.zuo`](local/hello.zuo),
[`local/tree.zuo`](local/tree.zuo),
[`local/image.zuo`](local/image.zuo), and
[`build.zuo`](build.zuo).
Building and Running Zuo
------------------------
Compile `zuo.c` with a C compiler. No additional files are needed,
other than system and C library headers. No compiler flags should be
needed, although flags like `-o zuo` or `-O2` are a good idea.
You can also use `configure`, `make`, and `make install`, where `make`
targets mostly invoke a Zuo script after compiling `zuo.c`. If you
don't use `configure` but compile to `zuo` in the current directory,
then `./zuo build.zuo` and `./zuo build.zuo install` (omit the `./` on Windows)
will do the same thing as `make` and `make install` with a default
configuration.
The Zuo executable runs only modules. If you run Zuo with no
command-line arguments, then it loads `main.zuo`. Use the `-c`
flag to provide module text as an argument. Otherwise, the first
argument to Zuo is a file to run or a directory containing a
`main.zuo` to run, and additional arguments are delivered to that Zuo
program via the `runtime-env` procedure. Running the command
`./zuo build install`, for example, runs the `build/main.zuo` program
with the argument `install`. Whatever initial script is run, if it has
a `main` submodule, that submodule is also run.
Library Modules and Startup Performance
---------------------------------------
Except for the built-in `zuo/kernel` language module, Zuo finds
languages and modules through a collection of libraries. By default,
Zuo looks for a directory `lib` relative to the executable as the root
of the library-collection tree. You can supply an alternate collection
path with the `-X` command-line flag.
You can also create an instance of Zuo with a set of libraries
embedded as a heap image. Embedding a heap image has two advantages:
* No extra directory of library modules is necessary.
* Zuo can start especially quickly, competitive with the fastest
command-line programs.
The `local/image.zuo` script generates a `.c` file that is a copy of
`zuo.c` plus embedded modules. By default, the `zuo` module and its
dependencies are included, but you can specify others with `++lib`. In
addition, the default collection-root path is disabled in the
generated copy, unless you supply `--keep-collects` to
`local/image.zuo`.
When you use `configure` and `make` or `./zuo build.zuo`, the default
build target creates a `to-run/zuo` that embeds the `zuo` library, as
well as a `to-install/zuo` that has the right internal path to find
other libraries after `make install` or `./zuo build.zuo install`.
You can use heap images without embedding. The `dump-heap-and-exit`
Zuo kernel primitive creates a heap image, and a `-B` or `--boot`
command-line flag for Zuo uses the given boot image on startup. You
can also embed an image created with `dump-image-and-exit` by using
`local/image.zuo` with the `--image` flag.
A boot image is machine-independent, whether in a stand-alone file or
embedded in `.c` source.
Cross Compiling
---------------
If you use `./configure --host=...` to cross compile, then you will
also need to add something like `CC_FOR_BUILD=cc` as a `./configure`
argument to specify the compiler for a `zuo` to use on the build
machine. If necessary, you can also specify `CFLAGS_FOR_BUILD`,
`LDFLAGS_FOR_BUILD`, and/or `LIBS_FOR_BUILD`.
Embedding Zuo in Another Application
------------------------------------
Zuo can be embedded in a larger application, with or without an
embedded boot image. To support embedding, compile `zuo.c` or the
output of `local/image.zuo` with the `ZUO_EMBEDDED` preprocessor macro
defined (to anything); the `zuo.h` header will be used in that case,
and `zuo.h` should also be used by the embedding application.
Documentation for the embedding API is provided as comments within
`zuo.h`.
More Information
----------------
Install the `zuo-doc` directory as a package in Racket to render the
documentation there, or see
[docs.racket-lang.org](https://docs.racket-lang.org/zuo/index.html).