Skip to content
BranchesTags

Repository files navigation

README

The goal is to write programs in KLIC, the implementation of KL1 that compiles on Unix systems.

The project behind KL1 is ICOT, which is now closed. There was a Debian package until 2006, whose binaries were 32-bit.

To recreate the package on a more modern distro, I used Ubuntu 16.04 Trusty i686.

Prerequisites

The Vagrantfile requires the vagrant-disksize plugin (it sets the VM disk size). Install it once before bringing the VM up:

vagrant plugin install vagrant-disksize

Do not install vagrant-vbguest. The ubuntu/trusty32 box already ships with Guest Additions, which are enough for the /vagrant synced folder. On a mismatch (box GA 4.3.40 vs a modern VirtualBox) Vagrant only prints a harmless warning and continues. The vagrant-vbguest plugin (0.32.0), on the other hand, crashes vagrant up on current Vagrant: it calls File.exists?, which Ruby 3.2+ removed, and Vagrant 2.4.9 embeds Ruby 3.3. If it is already installed, remove it:

vagrant plugin uninstall vagrant-vbguest

How to use the ready-made packages

The trusty directory holds the .deb packages built for Trusty.

# create the VM
vagrant up
vagrant reload

# install the packages
vagrant ssh  #  log into the VM

cd /vagrant/trusty/
./install-latest.sh    # installs the newest klic + klic-doc .deb present (highest Debian version)

How to recreate the .deb packages

# create the VM
vagrant up
vagrant reload

# create the packages
vagrant provision --provision-with build_deb_packages

The packages end up in /home/vagrant/deb/ (that is inside the VM).

Using the Docker container

Instead of the Vagrant VM, you can build KLIC as a Docker image (Debian trixie, amd64 host; KLIC is compiled 32-bit via gcc -m32). This needs only Docker.

Build the image

docker build -t kl1c .

The build downloads the Debian klic 3.003-gm1 source, applies this repo's patches, builds the .debs and installs them, so klic is ready to use.

Run the container (mounting the repo)

Mount the repo at /work so you can compile the .kl1 files in place. The mount syntax depends on your shell:

Host shell Command
Linux / macOS / WSL docker run --rm -it -v "$PWD":/work kl1c
Windows PowerShell docker run --rm -it -v "${PWD}:/work" kl1c
Windows Git Bash MSYS_NO_PATHCONV=1 docker run --rm -it -v "$PWD":/work kl1c
Windows cmd.exe docker run --rm -it -v "%cd%":/work kl1c

On Windows (Git Bash) you must set MSYS_NO_PATHCONV=1, otherwise MSYS mangles the :/work target and the mount comes up empty. It is a harmless no-op on Linux/macOS/WSL, so every mount command below is prefixed with it and works on all platforms as written.

Build and test everything with make

The repo has recursive make targets. The container's working directory is /work (the mount), so make runs there by default:

# build every KL1 program (distribution examples + book examples, all chapters)
MSYS_NO_PATHCONV=1 docker run --rm -v "$PWD":/work kl1c make all

# run every test and example: tests/ compares each program's output to its .expected,
# the book examples are verified the same way, and the distribution examples are compiled
MSYS_NO_PATHCONV=1 docker run --rm -v "$PWD":/work kl1c make test

# remove all generated files
MSYS_NO_PATHCONV=1 docker run --rm -v "$PWD":/work kl1c make clean

make all/make test/make clean recurse into examples/, agent-oriented-programming/ (per chapter) and tests/ (per category), running the same target in each. make test prints one line per program (PASS / FAIL / RUN / CFAIL) and exits non-zero if anything fails.

You can also run a single subtree or category:

MSYS_NO_PATHCONV=1 docker run --rm -v "$PWD":/work kl1c make -C tests/float test
MSYS_NO_PATHCONV=1 docker run --rm -v "$PWD":/work kl1c make -C agent-oriented-programming test

Run a single example interactively

MSYS_NO_PATHCONV=1 docker run --rm -it -v "$PWD":/work kl1c
# then, inside the container:
make -C agent-oriented-programming/ch04-event-driven-condition-synchronization
./agent-oriented-programming/ch04-event-driven-condition-synchronization/primes_sieve  # -> [2,3,5,7,11,13,17,19,23,29]

cd examples && make fact && ./fact   # KLIC distribution example -> 39916800

See tests/README.md, agent-oriented-programming/README.md and examples/README.md for details. (tests/ also ships a run.sh runner with category filters and a configurable per-case timeout.)

Appendix: Downloading klic sources

  • We download a mirror of ICOT's free software (ifs: ICOT Free Software) from its online DVD; from 2005 through at least October 2020. It takes about 122 MB, with more software than just klic.
wget --tries=inf --timestamping --recursive --level=inf --convert-links --page-requisites --no-parent -R '\?C=' https://www.ueda.info.waseda.ac.jp/AITEC_ICOT_ARCHIVES/ICOT/ifs/
popd

# It may also be interesting to mirror ALL of ICOT, although too much is written in Japanese, and I
# understand none of it. (a couple of gigabytes)
wget --tries=inf --timestamping --recursive --level=inf --convert-links --page-requisites --no-parent -R '\?C=' https://www.ueda.info.waseda.ac.jp/AITEC_ICOT_ARCHIVES/ICOT/

Appendix: References

About

Kernel Language 1 to C Compiler

Resources

Readme
Activity

Stars

6 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages