README for Logiweb distribution Klaus Grue, 2009 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 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. Use e.g. 'head -n 1 src/*.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 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