
These are the release notes for shapeTools-1.4pl6

This document describes the changes made since ShapeTools-1.3. We
start with a short overview pointing to each part of the toolkit,
where changes were made. When you've been a ShapeTools user before,
you should in any case read the *Migrating from ShapeTools-1.3 to 1.4*
section following the overview.


Overview
--------
- Major restructuring of the entire system. This results in two new
  completely documented toolkit libraries AtFStk and Sttk (along
  with the AtFS base library).

- Version binding (version selection) has been factored out into the
  AtFS toolkit library. This allows uniform rule based version
  identification in all parts of the system. Earlier versions
  supported rule based version binding only in the shape program.

- More flexible and straightforward version bind rules, providing user
  customization of global rules, rule evaluation hierarchies,
  formulation of constraints with respect to other objects, and more.

- New version archive organization with subdirectories within the
  AtFS directory. This is important for people using filesystems with
  14 character filenames, as archive names are not any longer built by
  adding some magic characters to the filename, but rather by taking
  the filename itself.

- New command "mkatfs" for creating AtFS subdirectory structures.

- Some minor changes to the AtFS interface. This is only important for
  people who have own application programs operating directly on the
  AtFS programming interface.

- Better derived object cache handling.

- A lock daemon for locking of AtFS archive files during update.

- Reimplementation of the vl Program with the capability to show
  histories (-h option).

- Restructuring of all version control commands with introduction
  of the general version binding functionality in each command.

- New version control commands "vbind" (version binding), "cphist"
  (copy history), "vp" (paginated screen output of version contents),
  "vgrep/vegrep" (patched GNU grep - see below), "vgdb" (patched gdb -
  see below), "vattr" (attribute handling) and "vrm" (remove version).

- Removal of the commands "pattr" and "vinfo".

- New parser for Shapefiles. The syntax of Shapefiles has been
  slightly straightened (no need for the "#% RULE-SECTION / 
  #% END-RULE-SECTION" junk anymore).

- More powerful macro substitution schemes in Shapefiles (e.g. string
  substitution).

- 50% Speedup of the shape program.

- A package for GNU Emacs to provide full access to versions including
  version name completion, checkout (retrv) and checkin (save) from
  the edit buffer and full version binding capabilities.

- A patch to gdb (about 40 lines changed/added), enabling the source
  context to be read directly from the appropriate versions while
  debugging. This works only together with find_atfs when running gdb
  in an emacs window.

- A patch to GNU grep (basically a 4 lines patch) adding access to
  saved versions. This also implants full version binding.

- Changes to the release management system (RMS) featuring release
  documentation (logging) and better release number generation. 

- New command "lastrelease" indicating the name of the last generated
  (pre)release.

- A new porting strategy with only one central config.h/config.c
  file pair holding all host system dependent definitions.

- Introduction of the environment variable SHAPETOOLS.

- ANSI-C/POSIX conformance with documented exceptions
  (see src/atfs/config.h).

- Various bug fixes (and various new bugs =:-).


Migrating from 1.3 to 1.4
-------------------------
If you used ShapeTools 1.3 or earlier versions up to now for your
development work, you should read this section carefully.

As the internal organization of data in the AtFS directory was
changed, all version data needs to be converted. This can be done
by invoking the program "atfsrepair" on each AtFS directory.
Atfsrepair will create the necessary subdirectories in the AtFS
directory and will move all archives to the proper places. In
order to avoid later permission problems, it is important that all
subdirectories in an AtFS directory have the same owner, group and
protection as the AtFS directory itself. Hence,

  -> only the owner of the AtFS directory should perform the
     conversion.

atfsrepair will warn you, if this is not the case. Conversion is done
by calling

  -> atfsrepair [-n] [-q]

The -n (non-interactive) option causes atfsrepait to do it's job
without user interaction. The -q option is for quiet operation. As the
management of derived object caches has changed too, atfsrepair will
also remove all objects from the old derived object cache.

If you have any own shell scripts, Makefiles or Shapefiles using
ShapeTools version control commands, you should check, if these are
affected by changes to the version control system. All changes to the
version control system are listed in a subsequent section.


Version control system
----------------------
- Uniform version binding (version selection) throughout all commands.
  Version binding  is conducted by version bind directives (or just
  version bindings), which can be one of the following.
  + version numbers     (e.g. "1.2", "1.", ".2")
  + version alias names (e.g. "ShapeTools-1.4")
  + date specifications (e.g. "10.2.93", "Feb 10, 1993")
  + bind rule names (e.g. "mostRecent:", "fromRelease(ShapeTools-1.4)")
  Version bindings can be given either in brackets, directly following
  the name to be bound, or as option arguments. The following list
  names the most important version binding options.
  + "-bind <version binding>" option
  + "-rule <bind rule name>" option
  + "-since <version binding>" option for defining version ranges
  + "-before <version binding>" option           "
  + "-last" and "-lastsaved" option

- A new command "vbind", performing version binding.

- The "vl" (and "vlog") command was totally reimplemented. It now
  supports output of histories in an "ls" like manner. This means
  one entry per known name in a directory -- just try it (option -h).
  The interface has changed a lot...
  + vl understands the version binding options (see above).
  + Some options have been added for "ls" conformance:
    "-1", "-A", "-c", "-d", "-F", "-g", "-L", "-q", and "-u"
  + New options are: "-?", "-expand", "-h", "-help", "-noexpand",
    "-O", and "-U".
  + The "-A" and "-L" option have now a different meaning as before
    for sake of "ls conformance.
  + "-B" and "-b" are now "-cache".
  + "-H" was renamed to "-log".
  + "-q" was renamed to "-Q" for sake of "ls" conformance.
  + The semantics of the "-locker" option was extended.
  + New optionm "-lll" short for "-l -locker -locked"
  + The following options are gone: "-#", "-archive", "-author",
    "-last", "-m", "-noenv", "-owner", "-s", "-ux", "-V", "-v", and
    "-vnum".
  + The "-u", "-U", "-uda" and "-Uda" options have been replaced
    by "-attr" and "-p"

- "save"
  + understands the version binding options (see above).
  + "-f" now also available as "-force".
  + "-h" option was renamed to "-?/-help".
  + "-m" now also available as "-logmsg".
  + "-q" now also available as "-quiet".
  + "-n" option was renamed to "-a"/"-alias".
  + "-newgen" now also available as "-g".
  + "-setvnum" now also available as "-n".
  + "-t" option was deleted. Use "-m @filename" instead.

- "retrv"
  + understands the version binding options (see above).
  + "-d", "-date", "-g", "-last", "-s", and "-V" options are deleted.
    Use the general version binding options instead.
  + "-a" option was deleted.
  + New option "-c/-copy"
  + "-f" now also available as "-force".
  + "-h" option was renamed to "-?/-help".
  + "-i" now also available as "-intent". The semantics of the "-i"
    option was slightly changed. Filenames have to be preceded by and
    at-sign ("-f @filename").
  + "-q" now also available as "-quiet".

- "vadm"
  + "-b" option was renamed to "-cache".
  + "-delete" now also available as "-d".
  + "-f" now also available as "-force".
  + "-h" option was renamed to "-?/-help".
  + "-l" now also available as "-lock".
  + "-q" now also available as "-quiet".
  + "-setuda" and "-remuda" are replaced by "-attr <attribute expression>
	attribute expressions are e.g. foo=blubber, otto=+berta, hugo=-bar
  + "-setattrs" is now "-attr @<attrfile>".
  + "-symbolic" option was renamed to "-alias".
  + "-unsetuda" is now "-delattr".
  + "-lock" and "-unlock" now have an optional argument describing the
	generation to be locked. The argument may be a version number,
	version alias or a date specification.
  + new options "-unalias" and "-newgen".

- "vfind" 
  + "-h" option was renamed to "-?/-help".
  + "-bpool" option was renamed to "-cache".

- New commands "vp", "vattr", "vrm", "cphist", and "mkatfs".
  ("vattr" and "vrm" are links to "vadm"

- Command "pattr" and "vinfo" deleted.


The shape program
-----------------
- Completely new parser for shape description files
  + no need for #% RULE-SECTION / #% END-RULE-SECTION pragmats
  + version selection rules are recognized by rule header "name :-"
  + variant defintions are recognized by header "name :+"
  + include directive takes lists of filenames
  + include directive takes filenames in macros
  + all syntactical stuff works robust now
  + in case of description file syntax errors a standard format
    error message is issued

- version binding has been completely rewritten, extended, and been 
  moved to the AtFStk library.
  + dynamic chaining of selection rules
  + more intuitive names for all the predicates, stripping the
    silly prefix "attr"
  + parametrization of selection rules

- much better diagnostics when shape fails to build a requested
  target

- additive macros can be set from the command line
- evaluative macro definitions, defining a macro substitution when 
  it is first referenced by evaluating the definition only once
- string substitution in macro evaluations
- accessing objects in variant subdirectories is now as fast as 
  accessing objects in the build directory
- new special macro in implicit rules, providing the full, version
  qualified id of processed objects
- new build-in macro SHAPEPID
- new build-in macro SHAPEVERSION
- consistent policy regarding *when* macros are substituted

- "-confid <target>" option renamed to "-bct", and changed into
  a command switch without argument. The bound configuration 
  thread document will be prepared for the requested targets, and be
  named <target name>.bct. bct-files are much more precise in 
  defining a bound configuration than the old "confids".
- "-D" option now provides detailed information on version binding 
  and derived object caching
- new switch "-h" (short for "-help")
- "-t" switch removed
- "-novclass" switch is new. It disables checking of incompatible 
  variant combinations
- "-expandall" renamed to "-xpon"
- "-expandnothing" renamed to "-xpoff"

- completely re-written manual page. All described features have
  been carefully checked. 

Release management system
-------------------------
- New command "lastrelease"
- Better support for variations of CFLAGS and LDFLAGS
- "lastrelease" attribute is tagged to each invoked version
	during prerelease or release.
- Status of versions is set to "published", when generation a
	"node release". This has been a bug in 1.3.
- Some new variant definitions in stdvar (s-svr4, gnu_posix...)
- Start a new generation for each component on "shape release"

Patches for gdb and GNU-diff
----------------------------
- A patch to gdb, enabling GNU gdb 4.8 to work on AtFS versions.
  This patch works on SPARC machines running SunOS 4.1.2 and is not
  tested with other platforms yet.

- A patch to GNU grep 1.6, enabling it to work on AtFS versions.

Both patches are new with ShapeTools-1.4. The patch files and two
corresponding README files are located in the directory "src/patches".
Applying the patches and installing the modified programs is *not*
supported by the ShapeTools installation procedure. You must do that
manually according to the instructions in the README files.


Emacs stuff
-----------
This is located in "src/interface" check also the README file there.

- New emacs lisp code find-atfs.el and callp-err.el
  + AtFS versions can be read directly into an Emacs buffer by
    invoking find-file with the version ID. (with version number
    or symbolic name).
  + Filename completion is done on version IDs as well.
  + If find-file tries to read a non-existent file, and an AtFS
    history of that file exists, the default version of this history
    will be read instead.
  + minor mode atfs-mode (without any features yet, but its name
    appears in the mode line)
  + toggle-read-only on a version checks a version out and a busy
    file in with asking for change intent resp. log message.
  + toggle-read-only on a file asks if the file shall be checked
    in as AtFS version.

- shapetools.el (ShapeTools-Mode) not available in shapeTools-1.4pl6.


Attribute Filesystem (AtFS)
----------------------------
- New functions
  + "af_establish" - establish version as UNIX file
  + "af_predsucc"  - get physical/logical predecessor/successor of
                     version
  + "af_cachesize" - get or set maximum size of derived object cache
  + "af_errmsg"    - get AtFS error message
  + "af_histories" - return a list of known history names

- Renamed functions and constants
  + "af_bpfind"     renamed to "af_cachefind"
  + "af_savebinary" renamed to "af_savecache"
  + "AF_DERIVED"    renamed to "AF_CLASS_DERIVED"

- Mode parameter of "af_lock", "af_unlock", and "af_testlock" removed.

- Additional storage type parameter to "af_savecache" and
  "af_saverev". Value is one of AF_STORE_DELTA, AF_STORE_COMPLETE, or
  AF_STORE_COMPRESSED.

- New manual pages
  + af_cache.3
  + af_error.3
  + af_history.3
  + af_protect.3 (formerly af_perm.3)


ShapeTools toolkit library and AtFS toolkit library
---------------------------------------------------
The shapetools toolkit library (sttk) and the AtFS toolkit library
(AtFStk) are two new libraries containing various basic functions
(sttk) and common functions based on AtFS (AtFStk) used throughout the
toolkit. They come along with a complete set of manual pages, st...(3)
and at...(3).


Porting
-------
New configuration files src/atfs/config.[ch]. The former configuration
files residing in src/atfs/conf/<system_name>/config.[ch] were
eliminated. Maintaining 14 files for 7 ports was too clumsy. Check the
file "INSTALL" for details on the new porting technique.


Patchlevel 1
------------

ShapeTools-1.4pl1 is mainly a bug-fix release. Other changes are:

- Due to numerous problems with the "fcntl" file locking, the old
  (shapeTools-1.3) archive file locking code was inserted again. It
  may be activated by defining "-DATFS_OWN_LOCKING"

- The gdb patch was updated for gdb 4.9. 

- mkatfs may now be used for reconfiguring the object cache.
