Stu -- Build Automation
=========================

This is Stu, a build tool in the spirit of Make, but with three features
that set it apart:

* Parametrized rules:  Like GNU Make's '%' character, but there can be
  multiple parameters, and they have names.  The syntax is '$NAME',
  where NAME can be any string.  Parameters are injected transparently
  into the commands.
* Dynamic dependencies:  The dependencies of a target can be generated
  dynamically.  When a dependency is enclosed in square brackets, it means
  that that file is built and dependencies are read from within that
  file.
* Parentheses and brackets support concatenation, allowing parametrized
  filenames to be generated in the first place.

In many scenarios, these three features interact judiciously to give
very concise and easy to understand constructs that are nearly
impossible to realize with Make.

See these blog articles for motivation:

https://networkscience.wordpress.com/2018/01/15/the-build-system-stu-in-practice/
https://networkscience.wordpress.com/2017/08/15/an-update-on-the-stu-build-system-stu-2-5/

For documentation, compile and read the manpage, or go directly to:

https://raw.githubusercontent.com/kunegis/stu/master/MANPAGE

For more specific documentation of particular aspects of Stu, see the
files in the doc/ directory.

------
 News
------

- Version 2.6 is out:  canonicalization of filenames is implemented

- Tip:  Set "export STU_OPTIONS=-E" in your .bashrc file to get
  explanations of common error messages in Stu.

See the file 'NEWS' for more news.

--------------------
 Installation Guide
--------------------

Stu is not yet in the main package repositories of common operating systems.
See the file INSTALL for compiling Stu yourself, which is easy: We use make and
make install.  Stu is written in C++17 for POSIX platforms.  You should have no
problem getting it to run on vanilla Linux and other POSIX-compliant platforms.

* See the file 'INSTALL' for compiling Stu
* Package for Arch Linux:  https://aur.archlinux.org/packages/stu-git/

If you're interested in making Stu packages available for other
operating systems and need help, please contact <kunegis@gmail.com>.

---------
 Use Stu
---------

To use Stu, replace your 'Makefile' with a 'main.stu' file, and instead
of calling 'make', call 'stu'.

To see an example of Stu used in a large data mining project, see the
file 'main.stu' in the KONECT-Analysis project:

https://github.com/kunegis/konect-analysis/blob/master/main.stu

-------
 About
-------

Stu was originally written to accommodate the KONECT project (Koblenz
Network Collection -- http://konect.cc/).  It is thus mainly used for
large data mining projects, where it manages everything from acquiring
data from the web, preprocessing data in various ways, to performing
data mining experiments, to generating plots and compiling the resulting
Latex papers.  It is also used for compiling C/C++ code, for generating
tarballs, for generating websites, and by data scientists and students
associated with Jérôme Kunegis.

The name "Stu" follows the precedents of Make replacements such as Cook,
Bake, and Brew in referring to kitchen-related verbs, and also honors
the author of the original Unix Make, Stuart Feldman.

Stu was initiated by Jérôme Kunegis at the University of Koblenz-Landau
(Germany), was then maintained at the University of Namur (Belgium), and is now
maintained by Jérôme Kunegis privately, with help from other contributors; see
the file AUTHORS.

Stu is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your
option) any later version.

Stu is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

For support, write to Jérôme Kunegis <kunegis@gmail.com>, or go to

https://github.com/kunegis/stu

Stu is a voluntary effort.  If Stu is useful to you, please donate:

https://www.paypal.com/donate?hosted_button_id=Q9JY2FB3AFHR6