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-<version>.tar.gz
> tar zxf logiweb-<version>.tar
> cd logiweb-<version>
> 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'.

Changing DESTDIR is not recommended. If you change it anyway,
note the following:

The system expects lgwam to be in /usr/bin/lgwam. If you set
DESTDIR to /foo then lgwam ends up in /foo/usr/bin/lgwam, so
you will need a symbolic link:

> ln -s /foo/usr/bin/lgwam /usr/bin/lgwam

If you do not want a symbolic link in /usr/bin, edit
/foo/usr/bin/lgc in an ordinary text editor and change the
first line to
  #!/foo/usr/bin/lgwam script
Furthermore, append a line to /foo/usr/bin/lgc saying</p>
  script=#!/foo/bar/lgwam script



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? <RETURN>
...
What keysize do you want? (2048) <RETURN>
...
Key is valid for? (0) <RETURN>
Key does not expire at all
Is this correct? (y/N) y <RETURN>
...
Real name: Klaus Grue <RETURN>
Email address: grue@diku.dk <RETURN>
Comment: <RETURN>
You selected this USER-ID:
    "Klaus Grue <grue@diku.dk>"

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
