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,

in order to fit into the same ecosystem as the wider Lua community:

• Lua;
• Tecgraf-provided/controlled projects, IM, CD and IUP;
• LuaRocks package manager; and
• The Rocks that the Assistant sources via LuaRocks.

Table of Contents:

1. About IM, CD and IUP
2. Why write the Assistant?
3. System Requirements and Recommendations (as at February 2022)
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-2022)?

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.

3. System Requirements and Recommendations (as at February 2022)

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: Grand total for a small project is roughly 1GB, in the
project tree alone. A crude estimate of OS-related disk usage is
perhaps 8-10GB. If the machine has 8GiB of RAM, a corresponding
swap partition may consume an additional equal amount of disk space...
adds up to perhaps 16GiB. I use a set of virtual machines for testing,
each with 8GiB RAM, but with no swap partition, and find that a
16GiB disk has about 7GiB free space when the OS plus Assistant
plus a small project is present.

Lua: For Ubuntu/GNU/Linux Mint, 5.1, 5.2, 5.3 or 5.4,
installed from the raw sources;

LuaRocks: Using latest stable 3.8.0, 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.

Operating Systems that have passed a trivial install/build/run test
(all OSes are 64-bit; GNU/Linux kernels 3.x, 4.x and 5.x):

• GNU/Linux Mint (MATE): 18.3, 19.3, 20.2 and 20.3;
• Ubuntu GNU/Linux: 18.04.3, 20.04.3 and21.10;
• CentOS 7 GNU/Linux: Supported;
• CentOS 8 GNU/Linux: (EOL) No longer supported;
• Rocky GNU/Linux 8.5: Supported;
• MX 21ahs GNU/Linux: Supported.

Network: Required to install Distro functional packages, 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 (probably with 4 or more CPUs/Threads).

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: Ubuntu, Mint, MX (21ahs), CentOS-7 or Rocky (8.5).
        # 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-2022 Grouse Software Pty Ltd.

ABN 061 107 855

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