Introducing lglicua:

• l -- Lua: https://www.lua.org/
• gl -- GNU/Linux
• icu -- PUC-Rio (Pontifical Catholic University of Rio de Janeiro)
  
          
  Tecgraf Institute of Technical-Scientific Software
  
          
  https://www.tecgraf.puc-rio.br/ :
  • i -- IM (Image Manipulation) https://sourceforge.net/projects/imtoolkit/
  • c -- CD (Canvas Draw) https://sourceforge.net/projects/canvasdraw/
  • u -- IUP (Toolkit for GUIs) https://sourceforge.net/projects/iup/
• a -- Assistant

The Assistant, including all documentation, is licensed under the
MIT License,
which is the same as is used by Lua, the Tecgraf packages IM/CD/IUP,
LuaRocks, and many resources available within the Lua community.

Table of Contents:

1. About IM, CD and IUP
2. Why write the Assistant?
3. System Requirements and Recommendations (as at June 2024).
4. Brief summary of Assistant components.
5. Initial Installer PROJECT/install/i (./i) script help:
6. Initial Build "quirky" PROJECT/build/q (./q) script help:

1. About IM, CD and IUP

IM, CD and IUP are products of the Tecgraf group at PUC-Rio.
The manager of the project within Tecgraf is Antonio Scuri, who
maintains day-to-day changes, as well as coordinating occasional
releases. The packages (as provided by Tecgraf) are very portable,
running on a number of operating systems, including both Windows
and the Ubuntu GNU/Linux distribution, as well as ARM and other CPU
architectures.

2. Why write the Assistant (2016-2024)?

I initially merely wanted to use the Tecgraf packages to put together a
small simulation package. I use Gentoo GNU/Linux as my base, with
C for low-level code integrated with system-installed Lua 5.1 (provided
by a Gentoo package), plus LuaRocks manager, plus some Rocks.

I failed to compile the sources under Gentoo. The documentation uses
Ubuntu as its reference for GNU/Linux support. After a struggle, the
build succeeded on Linux Mint, a fork of Ubuntu. However, build files
needed to be changed, and the compiler generated a significant number
of warnings. Further, I found that the release versions tended to have
bugs, but that these were quickly fixed in the public SVN repository.
Therefore, it was better to track the Subversion repository as
generally a more reliable set of sources. Updates to the repository
happened quite frequently.

This combination led to me automate the build/run process. Eventually,
I also prepared a separate installer, so that users did not need to
rely on manual instructions, and to support a broader range of Distros.
In particular, Red Hat distros CentOS-7, and Rocky 9, 9.1, 9.2 and
9.3, as well as Ubuntu-family MX GNU/Linx 21, 21.1, and 21.3.

There are two new features relating to installing Lua, both a result of
the evolution from OS-Package-based installation to source-based
installation. The first is that the Lua patchlevel may be specified
at installation time (e.g. ./i lua-install 5.4.4). This can be used to
override the selection of the latest version encoded in the Assistant
database. For example, 5.4.5, released 2023-04-29, was the latest
version for a few days, but was then withdrawn..

The second feature is that the user may optionally patch Lua before it
is built. Currently, only one patch is supported, and that is for newer
Lua 5.4 releases: A prototype "continue" keyword patch. The user
specifies this at installation time: "./i lua-install 5.4+continue".
The presence of all patches is announced in the version/copyright line:

From:  Lua 5.4.6  Copyright (C) 1994-2023 Lua.org, PUC-Rio
To:    Lua 5.4.6 +continue  Copyright (C) 1994-2023 Lua.org, PUC-Rio

*** I am indebted to David Sicilia for posting the original and revised
versions of the 'continue' patch to the lua-l mailing list,
and incorporating feedback throughout March 2023. You can see the
email thread on the mailing list archives.

I have reviewed the patch, changing it from a "git diff" to a
"diff -u" format, and have tried to rebase the patch on lua-5.2.6.
If there are defects in my work, I humbly apologise, and would be
grateful to receive fixes. ***

3. System Requirements and Recommendations (as at June 2024)

Assistant: A release tarball is about 300kB compressed; unpacked,
including a fresh Git snapshot of the sources, it occupies about
1.2MB.

OS-Installed libraries/facilities can occupy several dozen megabytes
of disk. This especially includes the C/C++ compiler. Other
OS-installed packages in this group include Lua, LuaRocks, Rocks,
and IM/CD/IUP third-party package dependencies.

Administrator (sudo): Needed extensively for Lua 5.1, LuaRocks, and
Tecgraf-required thiry-party libraries. The Assistant is structured
so that sudo is used heavily during installation, but is not needed
at all during day-to-day project development/operation.

IM/CD/IUP Repositories (fetched from the SourceForge master
repository via svn checkout): These occupy another 300-400 KB.
When these packages are expanded and compiled into a workspace, they
consume roughly an additional 250MB.

Disk space: At least 15GiB disk, assuming no swap partition.
OS, plus Assistant, plus Tecgraf sources and binaries may take 10GiB;
sometimes large updates, such as kernels, can consume significant space.
More space may be needed (32GiB? 64GiB?) depending on the project's
requirements.

Lua: One or more of 5.1 (5.1.5), 5.2 (5.2.4), 5.3 (5.3.6) or
5.4 (5.4.7); installed from the raw sources, and with a new option to
specify patchlevel (e.g. 5.4.4). Switching between main Lua versions
is easy, but remaining synchronised with LuaRocks may require
non-trivial additional actions;

LuaRocks: Using latest stable 3.11.1, installed as system Rocks
manager;

Rocks: std.normalize, std.strict, luasocket, luasec,
ldoc, bit32, luaposix. The Assistant adds value to the raw luaposix
Rock via a "pseudo-rock" called PosixExec.lua.

GNU/LinuxKernel: Kernels 4.x, 5.x and 6.x are supported.
(Untested: Some 2.x and 3.x kernels may work.)

Operating Systems that have passed a trivial install/build/run test
(all OSes are 64-bit):

• Ubuntu family:

  • GNU/Linux Mint (MATE): 21 and 21.1;
  • Ubuntu GNU/Linux: 18.04.3, 20.04.3 and 21.10;
  • MX21ahs GNU/Linux: 21, 21.1 and (NEW!) 21.3 (which uses Kernel 6);

• Red Hat family:

  • CentOS GNU/Linux: 7;
  • Rocky GNU/Linux: 9, 9.1, and 9.2 (Released 16 May 2023);

Network: Required to install Distro functional packages, Lua
sources, LuaRocks and selected Rocks, and to download IM/CD/IUP
Subversion files, probably from SourceForge, or possibly a local repository.

CPU + RAM + Disk:
Hardware sufficient to handle the significant workload of compiling and
linking thousands of lines of source code, potentially doing full
rebuilds multiple times per day, is highly recommended. A high-speed
disk resource (SSD drive, or perhaps RAID) may also be helpful.

Virtualisation:
Some incompatibilities (e.g. conflicting Lua versions) and also risks
associated with using sudo during installation on a machine may be
mitigated by running the entire Distro, Assistant and user project
in a virtual machine. For this case, I recommend that the host have
perhaps:

• 100 or more GiB of free disk space;
• 16GiB of RAM;
• fairly fast graphics; and
• a multi-core processor machine.

4. Brief summary of Assistant components.

The Assistant collects all files relating to a project under a single
directory, shown in this documentation as PROJECT. There are no
restrictions on multiple projects per person, or per machine, apart
from resource limitations such as disk space, CPUs and/or RAM.

Terse list of the six subdirectories under the top-level directory:

1. PROJECT/install/ [script ./i] and PROJECT/install/support/.
   
   A key goal is to push all Assistant operations requiring sudo
   into small, focussed installer steps, so no privileges are needed
   during day-to-day operation;

2. PROJECT/build/ [scripts ./q and ./parse-build.lua].

3. PROJECT/svn/ [script assistant-database.lua, several support
   scripts, plus checked-out copies of IM/CD/IUP Subversion (SVN)
   source trees].
   
   Most of the activity revolves around the assistant-database.lua
   script, and the majority of day-to-day operation is automated,
   but some infrequent items may need to be edited in by hand:

   • Patches to apply if the Assistant patch command is used;
   • Major release version details, including corresponding
     Subversion revision number and date/time stamp;
   • Possible OS library dependency updates; and
   • [...probably other items...].

4. PROJECT/1/ workspace: PROJECT/1/play and PROJECT/1/support.
   
   WARNING: Valuable in-progress files can easily be deleted if
   the workspace is "nuke"d -- regular workspace backups are
   highly recommended.

5. PROJECT/demos/: Initial scripts+files to place in workspace
   PROJECT/1/play area; and

6. PROJECT/patches/: Source code patches (e.g. svn diff im/src)
   given in unified "diff" format, from project (e.g. im)
   top-level directory.
   
   The patches are not applied by default; use build command patch
   to apply them.
   
   Note also that, for each patch,
   PROJECT/svn/assistant-database.lua must be edited to name the
   patch explicitly.
   
   In addition, patches should be reviwed occasionally for
   compatibility with master repository changes, especially when major
   releases of the Tecgraf packages occur.

5. Initial Installer PROJECT/install/i (./i) help:

    We assume a clean, currently-supported, fully-updated GNU/Linux distro:
    No Lua, no LuaRocks, no IM/CD/IUP sources or associated packages.  This
    Bash script prepares the overall environment.  **WE USE "sudo"
    EXTENSIVELY**, so that it is only very rarely needed after this
    installation phase.  If unsure, consult on-site expert(s).

        # DISTRIBUTION: Debian-based:  Ubuntu, Mint or MX (some versions);
        #               Red Hat-based: CentOS or Rocky (some versions).
        # LUAVER: 5.1, 5.2, 5.3 or 5.4.    Others (e.g. JIT) not supported.

        install$  ./i lua-install LUAVER  # Includes development files.

        # If a project space with valuable data is present:  SAVE IT BEFORE
        # PROCEEDING with "fer-real".  The old workspace is destroyed.

        install$  ./i lua-environment-force LUAVER
        install$  ./i lua-environment-force LUAVER fer-real

        install$  ./i reboot-now   # ->Terminal, ->$ cd PROJECT/install

        install$  ./i imcdiup-osdepend-install  # (Last sudo item.)
        install$  ./i imcdiup-svn-fetch
        install$  cd ../build

6. Initial Build "quirky" PROJECT/build/q (./q) help:

Usage: ./q DIRECTIVE [DIRECTIVE...] [CONFIRMATION]

This command is the main interface for day-to-day operation of the
Lua GNU/Linux IM/CD/IUP Assistant (lglicua), as well as providing
commands for less-frequent operations.  CONFIRMATION ("fer-real") is
optional:  If absent, the script pretends to operate, and simply shows
the intended commands.

Full help is split into separate pages:  Directive "help-index" gives
a table of contents.

Here is a sequence of commands to demonstrate the Assistant in action:
    - Build all required packages;
    - Change directory into the Assistant workspace's "play" directory;
    - Use Lua and the built libraries to get a GUI "hello, world"; and
    - Revert to the build directory:

    build$   ./q nuke,unpack,build,gather fer-real
             # ... Assuming build (Subversion sources) is successful...
    build$   pushd ../1/play
    1/play$  ./hello-world
    1/play$  popd
    build$

(End of main text of top-level IM/CD/IUP Assistant README.)

Copyright (C) 2021-2023 Grouse Software Pty Ltd.

ABN 061 107 855

All third-party copyrights and trademarks are the property of their
respective owners.