======================================================================
Abstract
======================================================================
ui-auto is a set of shell tools to manage software project
development.

1. Release automation

First of all, there is support for automation of software
release around the 'ui-auto-release' tool; it currently (Oct
2009) supports the build systems autotools and cmake and the
version control systems cvs, svn and git. Its basic goal is to
automate the reoccurring administrative duties around software
releases (like NEWS/ChangeLog files, VC tagging, uploading,
...). It also has a non-interactive mode that makes it suitable
for automated snaphot builds from cron, and a special Debian
mode to automate Debian package builds.

Tools: ui-auto-release, ui-auto-ubs, ui-auto-uvc, ui-auto-release-multi

2. Development help

Secondly, there is also a set of tools to help develop from VC
checkouts (simply via environment variables). This is useful if
you develop on several projects at the same time having
inter-dependencies.

Tools: ui-auto-env, ui-auto-shell, ui-auto-update

3. cmake and autotools library

There is small library for autotools (m4 macros) and cmake
(tests) to avoid redundancies per project for ui-auto
project. Using any of these is totally optional, though.


======================================================================
NEWS
======================================================================

=== Updating from 1.0.x->1.2.x NEWS ===

No changes (1) are needed to update projects using 1.0.x; you
will need to amend your project config if you want to use the
new Debian support, however.

(1) If you use autotools, the UI_INIT macro and have "long"
filenames in your project: Note that "tar-ustar
filename-length-max=155" is no longer hardcoded default as
automake option; instead, you now set automake options yourself
using arg 5 of UI_INIT: I recommend just using tar-pax nowadays:
'UI_INIT([src/foo/main.c],,,,[tar-pax])'.

=== Updating from 0.1.3 ===

Tools:
  - Command syntax changes fo all tools (ui-auto-*). See -h on any tool.

User configuration:
  - Migrate ~/.ui-auto-env.* into ~/.ui-auto.conf (see User Nutshell).

ui-auto enabled projects:
  - Only use the snippets in Developer Nutshell for configure.ac/Makefile.am;
    remove everything else that looks ui-autoish.
  - Generic check macro for other ui-auto projects is now "UI_CHECK"; also
    handles library packages.
  - Replace:
    - UI_CLEAN_DISTDIR_CRUFT -> UI_DISTDIR_CRUFT.
    - UI_LIB_CHECK_VERSION   -> UI_CHECK.
  - Remove all efforts for producing "version.h", "version.c" or
    "$PACKAGE-version" script; this is all handled automatically now.

======================================================================
Introduction
======================================================================

You might learn more in the (yet [Feb 2007] unfinished) introduction
(i.e., file INTRODUCTION). This file only contains some "quickstart
style" starters without much explanations.


======================
Nutshell: Installation
======================

This does not apply if you are using ui-auto via your distribution or
a standard local install.

However, if you intend to use ui-auto itself the "ui-auto" way --
i.e., directly from the version control directory:

a) Get (a version of) the ui-auto source tree [2006-Oct: svn://svn.schlund.de/ssr/trunk/ui-auto].
b) Configure your ~/.ui-auto.conf for ui-auto (see User Nutshell below); name it "ui_auto".
c) Taint your shell to use that very ui-auto source tree:

   eval `<ui-auto-source-tree>/src/tools/ui-auto-env ui_auto`

   If you are not working with different versions frequently, you might
   want to automate that in, e.g., ~/.profile.


===========================================
User Nutshell: Use ui-auto enabled projects
===========================================

a) Add a file "~/.ui-auto.conf", and add the project(s) you want to
   use with ui-auto.

   Use the proivided '.user.ui-auto.conf' sample file as template, and
   adapt to your needs.

b1) Taint your shell:

   eval `ui-auto-env project1`   : Environment ready to use project1.
   eval `ui-auto-env -d project1`: Environment ready to use project1 and all its dependencies.

b2) Or (easier): Create new dedicated shells:

   ui-auto-shell ui-auto-env project1: Shell ready to use project1.
   ui-auto-shell -d project1`        : Shell ready to use project1 and all its dependencies.

c) ui-auto-strap -c && ./configure && make

d) b) and c) can also be automated in a separate shell using the
"ui-auto-update" tool; see ui-auto-update -h.

===================================================
Developer Nutshell: Manage ui-auto enabled projects
===================================================

1. Add file ".ui-auto.conf" to top level; see 'ui-auto-release -p|-P'
   for all options, their defaults and descriptions.
2. configure.ac:
   - Add macro UI_INIT after AC_INIT.
   - Add any number of additional UI_* macros later if needed.
3. Makefile.am: Add this snippet
--
@UI_AUTO_AM@

all-local: ui-auto-all
clean-local: ui-auto-clean
distclean-local: ui-auto-distclean
install-data-local: ui-auto-install-data
install-exec-local: ui-auto-install-exec
uninstall-local: ui-auto-uninstall
dist-hook: ui-auto-dist
---
  This should give you full support for all UI_* macros called from configure.ac.

===================================================
Release Nutshell: Manage releases via ui-auto-release
===================================================
[moved for ui-utilcpp README 2008-JAN-08; may need some updates, but is basically correct.]

Package Versioning Scheme
-------------------------
ui-auto-release automates the release prodedure in this
package. ChangeLog can be produced automatically from VC logs.

VERSION="MAJOR.MINOR.DATE" (1.0.* and smaller)
VERSION="MAJOR.MINOR.PATCH" (1.1.0 and greater)

MAJOR: Substantial changes.
MINOR: Odd numbers development versions, even numbers "stable" versions.
       Each time we postulate some release "stable", this number is increased
       by one (from odd to even), CVS is tagged, then increased again
       by one (from even to odd). Changes (and subsequent Patchlevel releases)
       to that stable version might be done later in a seperate branch (if
       needed).
DATE : Date in the form YYYYMMDD. Patchlevel releases.
PATCH: Patchlevel version.

 The initial development branch should be 0.1. The initial stable
branch should be 1.0 (rather than 0.2). From now on, the first number
should now only change for really substantial changes.

 So, release versions should develop like this (DATE is always computed
automatically):

Release   comes from

0.1.*  initial development branch.
1.0.*  initial stable branch.
1.1.*  development branch.
1.2.*  stable branch.
1.3.*  development branch.
...


Library Versioning Scheme
-------------------------

 This package uses "libtool" to create all libraries, and adopts the
"Libtool Versioning System" for shared libraries. Please see in
libtool's documentation.

 Main library versions and package versions relate to each other this
away:

Name                 Package Version    Library Main Version
1st unstable branch  0.1.*              0
1st stable branch    1.0.*              1
2nd unstable branch  1.1.*              2
2nd stable branch    1.2.*              3
...

 This way, odd library main versions denote stable versions; this is
simple and effective.

 As little drawback, we are not able to reflect interface incompatible
changes _inside_ an unstable branch by means of so-library
versioning. So if you do not relink, odd things might happen -- but
hey, it's unstable ;).

 At the same time, we are not able to reflect interface incompatible
changes _inside_ a stable branch -- but this is a feature, as the
interface _must_ not change thusly in a stable branch.
