README for Logiweb distribution Klaus Grue, 2010 Prerequisites - Logiweb is available under GNU GPL. - Installation requires make and gcc. - Running lgc requires gcc, latex, bibtex, makeindex, and dvipdfm. - If sources are modified, recompilation requires make, gcc, and xxd. Installation Logiweb is available in several formats like tar.gz, tar.bz2, rpm, deb, and as a Cygwin package. Consult http://logiweb.eu/ for download and installation instructions for each format. Installation instructions for the tar.gz version are as follows: > download logiweb-.tar.gz > tar zxf logiweb-.tar > cd logiweb- > make > make test (optional) > su > make install > exit If you run 'make test', note the following: - The testsuite takes a lot of time to run - Lots of text scroll over your window while the testsuite runs - The scrolling text contains lots of error messages; that is intended - If the testsuite succeeds, the output ends with 'Testsuite succeeded' - If the testsuite fails, it just stops or hangs without any message - If the testsuite fails, consult http://logiweb.eu/ for help The lgwam program has a compiled in testsuite. That testsuite is one among many tests executed by 'make test'. By default, only three test cases are included in the compiled in testsuite. To get the full testsuite with thousands of test cases, use 'make full' instead of 'make' above. Installing on Cygwin The following packages may be helpful: Devel/gcc: C compiler upgrade helper Called by most lgs-programmes at runtime Devel/make If you build from tar.gz or tar.bz2. Editors/nedit My choice for authoring Logiweb programs Editors/vim Includes the xxd command which you need if you do 'make test' Net/openssh If you want to talk with the outside world Text/tetex, Text/tetex-base, Text/tetex-extra Needed by the lgs backend for rendering pages X11/X-start-menu-icons If you want to see the output from the lgc backend Trying it out Issue > which lgc > which lgwam to see that those programs are installed. Issue > man lgc > man lgwam > man 5 lgc > man 5 lgc.conf > man 5 logiweb > man 7 logiweb to see that the man pages are installed. Issue > lgc --version > lgc --help > lgwam --version > lgwam --help to see that the commands can be invoked To compile something, cd to the directory containing this README, then do something like the following: > mkdir ~/mylgcdir > cp src/*.lgs ~/mylgcdir > cp src/logiweb.* ~/mylgcdir (only needed for 'lgc lgc' below) > cp src/version ~/mylgcdir (only needed for 'lgc lgc' below) > cp src/testsuite/pages/*.lgs ~/mylgcdir > cd ~/mylgcdir > lgc base If you get a segfault or a message about overflow of the C stack, try this if you run bash or similar: ulimit -s unlimited try this if you run chs or similar: unlimit stacksize try this if you run Cygwin: Add more RAM 'lgc base' is known to work with 2 GB RAM Then proceed thus: > lgc combinations > firefox combinations/index.html & Then browse around. Then try to execute some of the generated binaries: > base/page/bin/hello Hello World > base/page/bin/echo (echoes each character until it receives 'q') > base/page/bin/eecho (echoes each input character twice until it receives 'q') > base/page/bin/lgciotest (run small testsuite testing IO capabilities defined on the base page) Then try to compile some more files: > lgc check > lgc Peano > lgc multzero Then browse around. Even try to let the compiler compile itself: > lgc lgc Then try to execute the selfcompiled compiler: > lgc/page/bin/lgc --version Have fun. Troubleshooting In case you run into problems, go to http://logiweb.eu/ and read the mailing list archives (c.f. http://logiweb.eu/). If that does not help, subscribe to a suitable mailing list (c.f. http://logiweb.eu/) and post your question there. When you do so, make sure you include a copy of the following: An explanation of what you were trying to do A copy of the shell commands you issued and the response you got Output from 'lgc --version' Output from 'lgc --options' Output from 'uname -a' Output from 'gcc --version' Your /etc/logiweb/lgc.conf (if any) Your ~/.logiweb/lgc.conf (if any) Uninstallation: If you still have the make file, do 'make uninstall'. Otherwise, try this: > su > rm -f /usr/bin/lgc > rm -f /usr/bin/lgwam > rm -f /usr/share/man/man1/lgc.1 > rm -f /usr/share/man/man1/lgwam.1 > rm -f /usr/share/man/man5/lgc.5 > rm -f /usr/share/man/man5/lgc.conf.5 > rm -f /usr/share/man/man5/logiweb.5 > rm -f /usr/share/man/man7/logiweb.7 > rm -r -f /etc/logiweb > exit > rm -r -f ~/.logiweb Selfcompilation Use 'make self' to let the compiler compile itself using src/lgc. The result of the compilation ends up in ./self. ./self will have the same file structure as . itself. As an example, you can cd to self and do 'make self' again, leading to a self/self directory. A 'make self' ends by doing a diff between . and ./self. If no changes are reported, you have reached a fixed point. Use 'make fix' to do 'make self' repeatedly until a fixed point is reached (if ever). The fixed point ends up in ./self. Use 'make recompile' to let the compiler compile itself, but using /usr/bin/lgc. This is useful when you really mess with lgc.lgs and lgwam.c. The result ends up in src/lgc and src/pages.c. Configuration Once installed, you can configure the system using configuration files. The default locations of configuration files are /etc/logiweb/lgc.conf and $HOME/.logiweb/lgc.conf, c.f. 'man 5 lgc.conf'. Output from the lgc compiler ends in $HOME/.logiweb/ by default. By default, a link to the output is generated in the current directory. The lgc compiler dumps lots of megabytes in ~/.logiweb. Unfortunately, the present version of the distribution does not include a Logiweb Garbage Collector (lgwgc). The garbage collector of old versions (or, rather, the gc option of old versions of lgc) will not work with the new system. Chances are that lgwgc will be available before you run out of disk space. When doing 'make install', you can change the root of the installation by setting DESTDIR. If you do 'make uninstall' later, use the same value of DESTDIR as was used for 'make install'. Making GPG signature > gpg --gen-key ... Please select what kind of key you want: (1) DSA and Elgamal (default) (2) DSA (sign only) (5) RSA (sign only) Your selection? ... What keysize do you want? (2048) ... Key is valid for? (0) Key does not expire at all Is this correct? (y/N) y ... Real name: Klaus Grue Email address: grue@diku.dk Comment: You selected this USER-ID: "Klaus Grue " Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O You need a Passphrase to protect your secret key. ... > gpg --export --armor > ~/.gnupg/rpm-gpg-key Redistribution: Use 'make dist' to get a list of distribution targets. To make .tar.gz: make gz To make .tar.bz2: make bz2 To make RPM and yum archive: Ensure you run on a Linux supporting Rpm Package Management Ensure you have a GPG signature (see above) make rpm make rpmtest1 make rpmtest2 To make Debian package: Ensure you run on a Linux supporting Debian Package Management Ensure you have a GPG signature (see above) make deb make debtest1 EITHER make debtest2a OR make debtest2b (see makefile for details) To make Cygwin package Ensure you run on Cygwin make cyg Making new version: Make your changes Edit the VERSION variable in the makefile Get RPM timestamp using date +"%a %b %d %Y" Get Debian timestamp using date -R Edit CHANGELOG Edit src/dist/deb/debian/changelog Edit change log in src/dist/yum/rpmspec Ensure src/*.lgs and src/testsuite/pages/*.lgs have page headers. head -n 1 src/*.lgs head -n 1 src/testsuite/pages/*.lgs Ignore src/testsuite/pages/hello.lgs. make fix cd self make test (to test everything AND update page headers) Proceed as indicated in the section 'Redistribution' above Backporting The purpose of a backport is to construct a 0.1.x version which can generate the 'current version' where the 'current version' is the version which is current at the time of the backport. The current version is supposed to be compilable by itself and by its predecessor version. The 0.1.x backport, however, is supposed to be able to generate the current version from scratch. A backport results in a new 0.1.x version and a new current version. The smallest possible change in the current version is the addition of a changelog entry for the new 0.1.x version. Procedure: Copy current version to ./lgc/lgc Copy 0.1.x version to ./full/full Update both versions so they coincide Then check that they coincide as follows: In ./lgc/lgc: > make > make test > make clean Copy headers from ./lgc/lgc to ./full/full as follows: src/base.lgs -> lgc/base.lgs src/lgc.lgs -> lgc/lgc.lgs src/testsuite/pages/combinations.lgs -> lgc/combinations.lgs src/testsuite/pages/check.lgs -> lgc/check.lgs src/testsuite/pages/Peano.lgs -> lgc/Peano.lgs src/testsuite/pages/multzero.lgs -> lgc/multzero.lgs src/testsuite/pages/testmachine.lgs -> lgc/testmachine.lgs src/testsuite/pages/test.lgs -> test/testsuite.lgs A header is copied by replacing the second line of the target by the first line of the source. In ./full/full > make build Building ends by a call to diff. If diff reports no differences, the new 0.1.x and the new current version coincide. Make targets make Same as make all make all Compile lgwam make test Run testsuite make install Install lgc, lgwam, and man pages make uninstall Uninstall lgc, lgwam, and man pages make self Let the compiler compile itself make clean Clean up after 'make' and 'make self' Roadmap /usr/bin/lgc: Logiweb compiler /usr/bin/lgwam: Logiweb abstract machine /usr/share/man/man1/lgc.1 How to invoke the Logiweb compiler /usr/share/man/man1/lgwam.1 How to invoke the Logiweb Abstract Machine /usr/share/man/man5/lgc.5 The Logiweb programming language /usr/share/man/man5/lgc.conf.5 Format of Logiweb compiler configuration files /usr/share/man/man5/logiweb.5 Logiweb standard file formats and protocol /usr/share/man/man7/logiweb.7 Obsolete Logiweb protocol /etc/logiweb/lgc.conf Default location of site configuration file ~/.logiweb/lgc.conf Default location of user configuration file ~/.logiweb/logiweb/ Default location of compiler output ~/.logiweb/name/ Same as previous, but sorted by name