Note that is project is very much a work in progress in its early
stages. Although the intent is to make something which can be
approached by anyone, it isn't. It does work, however, for what it
is and so if doing nothing more than
make test
doesn't eventually say
All tests successful.
hopefully in a reassuring green colour then that's a major bug which
I would very much like to know about. Please see the file BUGS for
more information about known bugs and how to report any more that
you find.
On the other hand if you're prepared to roll your sleeves up you
can see the file HACKING for a brief overview of the lossless source
files and the run-time.
The rest of this file is written as though it's a normal README
written for a project which works and is complete.
Building Lossless is on the insides a two stage process: the first
stage, which can be bypassed, processes the CWEB sources (*.w) to
produce the printer (*.tex) and C (*.c & *.h) sources. The second
stage compiles the C sources to an executable, or the printer sources
to a readable document.
The Makefile has been carefully crafted to work with BSD and GNU
make but this is probably an impossible pipe dream in the long term.
Apart from the author's OpenBSD, Lossless has so far been known in
the past to build on Debian (et al) and FreeBSD.
TeX/CWEB:
The first build stage requires CWEB by Donald Knuth et al.
This is distributed as part of the astronomically huge TeX
Live system from https://tug.org/texlive/ which is available
in most unix systems (OpenBSD calls its "texlive_texmf-minimal";
Debian and derivatives use "texlive-extra-utils"; to find
the package yours provides it in look for one which contains
the file "cwebmac.tex").
The whole of TeX Live isn't necessary (TeX isn't needed to
run Lossless at all, only for the printable literature); instead
the original (tiny) CWEB can be downloaded from DEK's
website. It has no dependencies other than a C compiler[*].
Get it from https://www-cs-faculty.stanford.edu/~knuth/cweb.html
Alternatively, even that isn't necessary --- the intermediate
sources have been prepared in a downloadable archive available
from http://zeus.jtan.com/~chohag/lossless/.
Quirks:
The REPL has been removed from this development version and
so there is no `all' or `lossless' make target. The main
way to hack on lossless is through writing test cases and/or
hacking on evaluate.la/barbaroi.ll --- see HACKING.
To build on OpenBSD:
$ make test
Useful targets:
$ make # or make all Everything
$ make clean all Everything from scratch
$ make lossless Lossless executable
$ make liblossless.so As a linkable object
$ make ffi.perl Perl wrapper
$ make test Run losslees through a comprehensive test suite
The available documentation can be read from within the development
directory by updating MANPATH:
Note that there have been significant changes since this
documentation was first written which invalidates most of
it. The point was to define the documentations *structure*
though, and so it stays as-is for now. It's not like it's
going to pollute anyone's manpage namespace.
$ MANPATH=:$PWD/man
$ make man/mandoc.db Rebuild the manual pages' index
nb. makewhatis includes backup files (*~) in its index.
[*] It's amazing to think that 40 year old code hasn't picked up
any crutches to keep it going and that it still builds as-is
on the systems today but that's what you come to expect with
Donald Knuth.