vici Files

This is the README for release 0.12.920 of VICI.

This is maintenance release of 0.12. It upgrades to Qt6

If you have not done so already, you should also get and read the user guide.
It would be quite difficult to use VICI without the documentation for the
built in commands. 
https://ocratato-vici.sourceforge.io/pdf/vici-user-guide.pdf

The vici-editor program allows you to create scripts using a flow chart.
The scripts can be run using the vici program. 
The vici-admin program can be used to start setting up commands for use with vici
and the vici-search program can be used to find and classify commands.

This release includes some features for advanced users.
You can specify that the for-each command should use threads.
You can divide the processing into separate threads.
You can split and merge data flows using the Manifold object.

A command line version, vici-cli, is available if you wanted to run a script
from another script, or from cron.

The vici-cron program provides a means of running scripts according to
various schedules.

An installer is also included that installs .desktop files and mime types so
that the programs can be run from the main desktop menu, or from your file manager.
It will also install an autostart desktop file for the scheduler.
An installer in the editor allows scripts to be installed in the desktop menu.
Normally you will have to explicitly run the script, but scripts that are
installed in the desktop menu or are scheduled can be flagged to start as
soon as they are loaded.

Prerequisites
-------------

You will need the C/C++ development tools, plus the development versions
of the following:

libxml2
Qt - Version Qt6
	Note: You will need to include the QtSvg 
	module which may be packaged separately.
X libraries  (X11, Xext, Xi and Xt)

Optionally (see below)
lua	- version 5.4 as a shared library

You will also need the following programs:
envsubst
texi2any
(A copy of the docs for coreutils is provided, but you may want to get a version of
coreutils.texi that corresponds to the software installed on your machine.)

The desktop installer requires the following programs:
desktop-file-install
update-desktop-database
update-mime-database
xdg-mime


Lua Configuration
-----------------
Currently Lua is used just for testing the test harness itself.
You can build and run this version of VICI without Lua.

If you add
--enable-lua
to the configure command it will use the installed version of Lua.

If you need to test an alternative version of Lua then add the path
to the package configuration file to PKG_CONFIG_PATH, for example
$ export PKG_CONFIG_PATH=/opt/Lua/5.3.4/share/lua/5.3:$PKG_CONFIG_PATH


Installation from a distribution
--------------------------------
As a normal user:

Unpack the tar file.
Change directory to the unpacked directory.
Create a build directory. 

Note that building from the build directory is no longer a mandatory
requirement, but it is still the recommended procedure.
It remains a requirement that $VICI points to the directory containing configure.

$ export VICI=$(pwd)
$ mkdir build
$ cd build

Then run configure from the build directory so that the temp files
don't clutter up the source. This may take a little longer than normal
since each of the sub-projects has its own configure which are run consecutively.

$ ../configure --prefix=$VICI

Then build it
$ make

Or if you want to keep a log of the build
$ make 2>&1 | tee make.log

-----------------------------------------------

If you have Qt installed in a non-standard location or have more than one version
installed you can specify it by giving the path to its package configuration file.

For example if a package file was /opt/Qt/5.5/gcc_64/lib/pkgconfig/Qt5Core.pc
you would use the --with-qt-pkg option:

$ ../configure --prefix=$VICI --with-qt-pkg=/opt/Qt/5.5/gcc_64/lib/pkgconfig

------------------------------------------------

Confirm that the build has been successful.
Capturing the output into check.log will make it easier to resolve problems.  

$ make check 2>&1 | tee check.log

(Note that during the check GUI programs should automatically run their tests and exit,
and there will be a delay of about ten seconds during one test which confirms a timeout.)

If a test of a GUI seems to get stuck please ensure the mouse cursor is placed over the
application window. If this has no effect select the Exit menu option or close the window.

The F5 function key can be used to pause and resume the GUI tests.

-------------------------------------------------

When things go wrong or if you just want to let us know that it worked you can mail me
at brenton-ross@users.sourceforge.net. 

Please include what distribution and desktop you are using.

*** For configure errors ***
Find which sub-project failed:
$ cd $VICI/build
$ grep '=== configuring in' config.log

Example results:
configure:5413: === configuring in src/cfi (/home/brenton/Software/Vici/vici-0.10/build/src/cfi)
configure:5413: === configuring in src/gth (/home/brenton/Software/Vici/vici-0.10/build/src/gth)

The last result will be the one that failed.
Go to the failed sub-project:
$ cd src/gth  # substitute the last one from your results

You can examine the config.log in that directory for some indication of what went wrong
or send it to me at the above address as an attachment to your email.

*** For make errors ***
Please send me the lines from the make output that show the error, and a few lines leading up
to it.

*** For make check errors ***
If the make check should fail when building a test program please send me the output of make 
check that show the error, and a few lines leading up to it.

If running a test should fail then please run the script getlogs.sh
and send vici-check-logs.tgz as an attachment to your email.

-------------------------------------------------

During this test phase of VICI's development it is recommended that the
programs be installed in the build area.

$ make install

You may want to set $VICI in your ~/.bash_profile and add it to your $PATH.

-------------------------------------------------

Since VICI is still in the development phase it is not recommended that it be
installed into the system directories. However if you must...

To install into the usual /usr/local directories:

If you have installed into a test area you will need to clean out the build:
$ cd build
$ make uninstall
$ make distclean

$ export VICI=/usr/local
$ cd build
$ ../configure --prefix=$VICI
$ make
$ sudo make install

You should probably adjust the entries in $VICI/share/vici/vici.xml so that
the logs are placed in a suitable location, such as in /var

-------------------------------------------------------------------

Optionally you can install the desktop files and mime types.
This is done after the make install step.

$ cd $VICI
$ ./desktop.install

If you are installing into the system directories:
$ sudo ./desktop.install

(The program will install to locations according to the user.)

You might need to log out and back in for the changes to appear in menus.

-------------------------------------------------

Installation from SVN Checkout
------------------------------
Create a project directory for VICI and cd into it.
$ mkdir vici
$ cd vici
$ export VICI=$(pwd)
Checkout the VICI project.
svn checkout svn://svn.code.sf.net/p/ocratato-vici/code/trunk src
Change directory to the top/src project directory.
$ cd src/top/src
$ chmod +x setup.sh
$ ./setup.sh
$ cd ..
$ mkdir build
$ cd build
$ ../configure --prefix=$VICI
$ make

---------------------------------------------------------------------

In order to use the VICI programs you will need to set the VICI environment
variable in your .bash_profile.

---------------------------------------------------------------------

User and Administration Documentation
-------------------------------------

This is available for download from SourceForge:
https://sourceforge.net/projects/ocratato-vici/files/vici-user-guide.pdf/download

Online versions are available from VICI's web site:
https://ocratato-vici.sourceforge.io/