Ubuntu Manpage: aefstate - aegis file state file

NAME

        aefstate - aegis file state file

SYNOPSIS

        project/info/change/[0-9]/[0-9][0-9][0-9].fs

DESCRIPTION

        A  file  state  file  is  used  to  store information about the files in a transaction.  These files are
        created and maintained by aegis.  These files should not be edited by humans.  These files is  owned  by
        the project owner and group.

src = [ { ... }, ... ];
This field is a list of all the files in the change. The records have the form

file_name = string;
This file names the file. The name is relative to the root of the baseline directory
tree.

uuid = string;
This field uniquely identifies the file for its entire lifetime. This field remains
constant across file renames. The value of this field shall be formatted as a valid
UUID, all in lower case.

action = (create, modify, remove, insulate, transparent);
This field describes what is being done with the file.

create The file is being created. Once integrated, the edit fields record the file
version created and stored in the history.

modify The file is being created. Once integrated, the edit fields record the file
version stored in the history.

remove The file is being created. The edit field is only informational, and describes
the file version at the time it was removed from the repository.

insulate
The file is insulating a development directory from changes to the baseline, it
shall be uncopied before development may end. This action shall only be present
in changes. It shall never be present in branch change state files.

transparent
The file wasonce present in the branch, however it is desired that the ancestor
version "show through". This is the equivalent of "uncopy" for branches. When
the branch is integrated, this file will be omitted.

edit = { ... };
For a project or an active branch, this field records the head revision of the file.
For a completed change or branch, this field records the revision number after integrate
pass.

revision = string;
This is the edit number, as reported by the history_get_command in the project
config file at integrate pass time.

encoding = (none, quoted_printable, base64);
This field records the encoding used when the file was added to the history at
integrate pass time, as configured by one of the history_put_command or
history_get_command and history_content_limitation fields of the project config
file.

none No encoding was applied to the file. Either it had no binary
characters, or the history tool is able to cope with binary files.

quoted_printable
The MIME Quoted Printable encoding (see RFC 1521) has been used to
escape the binary characters of the file content.

base64 The MIME Base 64 encoding (see RFC 1521) has been used to encode the
file content.

The history_content_limitation field of the project config file is used to
determine which files need encoding. The size of the encoded file is compared
to determine which of quoted printable and base 64 encodings is used; the
smaller is chosen.

edit_number = string;
This field is obsolescent. It is only present for backwards compatibility. It has been
replaced by the edit field.

edit_origin = { ... };
This field records the edit number of the file when it was added to the change or
branch. In changes, this field is not present for new files. (A change file is out of
date if it's edit number_origin field does not equal the edit_number field in the
project.)

It has the same fields, with the same meaning, as the edit field, above.

edit_number_origin = string;
This field is obsolescent. It is only present for backwards compatibility. It has been
replaced by the edit_origin field.

edit_origin_new = { ... };
This field records the edit number of the file to replace the edit_number_origin field
in the branch at integrate pass time. This is used to perform cross branch merging.
This field cleared at integrate pass time.

It has the same fields, with the same meaning, as the edit field, above.

edit_number_origin_new = string;
This field is obsolescent. It is only present for backwards compatibility. It has been
replaced by the edit_origin_new field.

usage = (source, config, build, test, manual_test);
This field describes what function the file serves.

file_fp = fingerprint;
This field records the last time modified of the source file. It is only present
between the being_developed and being_integrated states, inclusive (for both changes and
branches). It is not present for files which are being deleted. This field is used to
determine if a difference has been done, or a test has been done if the source file is a
test, and if the file has been tampered with before state transitions.

The fingerprint consists of the following fields:

youngest = time;
The youngest time see for this file with this fingerprint.

oldest = time;
The oldest time see for this file with this fingerprint.

crypto = string;
This field records a cryptographically strong fingerprint for the file. There
is no known method of constructing a file to match a given fingerprint, and
there is less than 1 in 2**200 chance that two files will have the same
fingerprint. Thus if the fingerprint is the same, the file can reliably assumed
to be the same.

diff_file_fp = fingerprint;
This field records the last time modified of the difference file when the last aegis
-DIFFerence command was run. It is only present between the being_developed and
being_integrated states, inclusive (for both changes and branches). This field is used
to determine if a difference has been done, and if the difference file has been tampered
with before state transitions.

idiff_file_fp = fingerprint;
This field records the last time modified of the integration difference file when the
last aegis -DIFFerence command was run. It is only present in the being_integrated
state. This field is used to determine if a difference has been done.

architecture_times = [{ ... }];
This field records the time of various operations for each variant named in the
architecture field. It is only present in the being_developed and being_integrated
states. This field is used to determine if a test has been done, and thus optimize test
runs.

variant = string;
This field is one of the patterns named in the architecture field.

test_time = time;
This field records the last time the last successful aegis -Test command was run
for this specific pattern instance.

test_baseline_time = time;
This field records the last time the last successful aegis -Test -BaseLine
command was run for this specific pattern instance.

move = string;
To change the name of a file, a combination of deleting the old name and creating the
new name is used. With deleted files, this field is used to say where it went. With
new files, this field is used to say where it came from.

locked_by = integer;
The change which locked this file.
Caveat: this field is redundant, you can figure it out by scanning all of he change
files. Having it here is very convenient, even though it means multiple updates.

about_to_be_created_by = integer;
The change which is about to create this file for the first time. Same caveat as above.

about_to_be_copied_by = integer;
For each change file that is acting on a project file from a deeper baseline than the
immediate parent project's baseline, the file needs to be added to the immediate parent
project. Note that this field says that this file record is a place marker, so that it
can be deleted again should the change not be integrated for some reason.

deleted_by = integer;
The change which last deleted this file. We never throw them away, because (a) it may
be created again, and more important (b) we need it to recreate earlier deltas.

test = [ string ];
This field is used to remember test correlations for source files. This is used by aet(1) to
suggest suitable tests.

metrics = [ { ... } ];
This field is used to describe various file metrics. It is committed during aeipass(1), when
the file is added to the history. The name must be given, and exactly one value.

name = string;
This is the name of the metric. This field must be set.

value = real;
This is the value of the metric. This field must be set. (If you have an integer-
valued metric, just use integers, Aegis will cope. If you have a string-valued metric,
assign integers to the enumerands.)

executable = boolean;
This field is used to remember whether the source file had any executable permission bits set at
develop end time. This mode will be restored (taking the project umask into account) when the
file is copied.

This field is only meaningful for changes in the completed state, because this field is only set
by aeip(1). Until then, the mode if the file itself is the authority.

attribute = [ { ... } ];
This is a list of (name,value) pairs, defining user specified attributes.

name = string;
The name of the attribute. By convention, names which start with an upper-case letter
will appear in listings, and lower-case will not. Attribute names are case-insensitive.

value = string;
The value of the attribute.

Arguably, most file properties which may be altered by the user (and some that can't) should be
of this form. Due to an accident of history, this is not the case.

WRITING REPORT SCRIPTS

        When  attempting  to  access  these  fields  from  within the report generator, you need a code fragment
        similar to the following:
                auto ps, pfs;
                ps = project[project_name()].state;
                fps = ps.src["somefile"];
                auto cs, cfs;
                cs = ps.branch.change[change_number()];
                cfs = cs.src["somefile"];
        Notice that the top-level fields of the file state are not available, but instead are  mapped  onto  the
        relevant project file and change file src arrays.

        All  of the src member fields mentioned in the man page can now be accessed as members of the pfs or cfs
        variables.

COPYRIGHT

        aegis version 4.24.3.D001
        Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,  2005,
        2006, 2007, 2008, 2009, 2010 Peter Miller

        The  aegis  program  comes  with  ABSOLUTELY  NO  WARRANTY; for details use the 'aegis -VERSion License'
        command.  This is free software and you are welcome to redistribute it  under  certain  conditions;  for
        details use the 'aegis -VERSion License' command.

AUTHOR

        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/

Reference Manual                                      Aegis                                          aefstate(5)