Provided by: aegis_4.21-2_i386 bug

NAME

       aegis -Develop_Begin - begin development of a change

SYNOPSIS

       aegis -Develop_Begin change-number [ option...  ]
       aegis -Develop_Begin -List [ option...  ]
       aegis -Develop_Begin -Help

DESCRIPTION

       The aegis -Develop_Begin command is used to commence development of a
       change.

       The development directory for the change will be created automatically;
       below the directory specified in the default_development_directory
       field of aeuconf(5), or if not set below the directory specified in the
       default_development_directory field of aepattr(5), or if not set below
       the current user’s home directory.  It is rare to need to know the
       exact pathname of the development directory, as the aecd(1) command can
       take you there at any time.

       Successful execution of this command will move the specified change
       from the awaiting development state to the being developed state.
       boxwid = 1 down S1: box "awaiting" "development" arrow " develop" ljust
       " begin" ljust S2: box "being" "developed" T1: spline -> from S2.w then
       left 0.75 then up 11/12    then to 1/3<S1.sw,S1.nw> " develop" ljust "
       begin" ljust " undo" ljust at T1.c - (0.75,0)

   Notification
       The develop_begin_command in the project configuration file (see
       aepconf(5) for more information) will be run, if specified.  This is
       run after the aegis locks are released, so additional aegis commands
       may be run from here, if used with care.  The symbolic links (see
       below) have not yet been created.

   Development Directory Location
       Please Note: Aegis also consults the underlying file system, to
       determine its notion of maximum file size.  Where the file system’s
       maximum file size is less than maximum_filename_length, the filesystem
       wins.  This can happen, for example, when you are using the Linux
       UMSDOS file system, or when you have an NFS mounted an ancient V7
       filesystem.  Setting maximum_filename_length to 255 in these cases does
       not alter the fact that the underlying file systems limits are far
       smaller (12 and 14, respectively).

       If your development directories (or your whole project) is on
       filesystems with filename limitations, or a portion of the
       heterogeneous builds take place in such an environment, it helps to
       tell Aegis what they are (using the project config file’s fields) so
       that you don’t run into the situation where the project builds on the
       more permissive environments, but fails with mysterious errors in the
       more limited environments.

       If your development directories are routinely on a Linux UMSDOS
       filesystem, you would probably be better off setting
       dos_filename_required = true, and also changing the
       development_directory_template field.  Heterogeneous development with
       various Windows environments may also require this.

ADMINISTRATOR OVERRIDE

       It is possible for project administrators to use the -User option to
       force a developer to start developing a change.  Some sites prefer to
       work this way.  Note that developers still have the ability to use the
       aedbu(1) command.

       Warning: capricious use of this command will rapidly alienate
       developers.  The defaulting rules, particularly for the change number,
       depend on aegis and the developer agreeing on what the developer is
       currently working on.

       The forced_develop_begin_notify_command project attribute (see
       aepattr(5) for more information) will be run when an administrator uses
       the -User option, in an attempt to minimize the surprises for
       developers.  A suitable command is
              forced_develop_begin_notify_command =
                  "$datadir/db_forced.sh $p $c $developer";
       This command will send e-mail to the developer, informing her that the
       change has been assigned to her.

SYMBOLIC LINKS

       Many dependency maintenance tools, and indeed some compilers, have
       little or no support for include file search paths, and thus for the
       concept of the two-level directory hierarchy employed by Aegis.  (It
       becomes multi-level when Aegis’ branching functionality is used.)  To
       allow these tools to be used, Aegis provides the ability to maintain a
       set of symbolic links between the development directory of a change and
       the baseline of a project, so it appears to these tools that all of the
       project’s files are present in the development directory.

   Project Configuration
       The development_directory_style field of the project configuration file
       controls the appearance of the development directory.  See aepconf(5)
       for more information.

       By using a setting such as
              development_directory_style =
              {
                  source_file_symlink = true;
                  during_build_only = true;
              };
       the user never sees the symbolic links, because they are added purely
       for the benefit of the dependency maintenance tool during the execution
       of the aeb(1) command.

       By using a setting such as
              development_directory_style =
              {
                  source_file_symlink = true;
              };
       (the other will default to false) the symbolic links will be created at
       develop begin time (see aedb(1) for more information) and also
       maintained by each aeb(1) invocation.  Note that the symbolic links are
       only maintained at these times, so project integrations during the
       course of editing change sourec files may leave the symbolic links in
       an inconsistent state until the next build.

       When files are copied from the baseline into a change, using the
       aecp(1) command, the symbolic link pointing into the baseline, if any,
       will be removed before the file is copied.

       Note: Using this functionality in either form has implications for how
       the rules file of the dependency maintenance tool is written.  Rules
       must remove their targets before creating them (usually with an rm -f
       command) if you use any of the link sub-fields (both hard links and
       symbolic links).  This is to avoid attempting to write the result on
       the symbolic link, which will point at a read-only file in the project
       baseline.  This is similar to the same requirement for using the link_
       integration_directory field of the project configuration file.

   User Configuration
       There is a symbolic_link_preference field in the user configuration
       file (see aeuconf(5) for more information).  This controls whether
       aeb(1) will verify the symbolic links before the build (default) or
       whether it will assume they are up-to-date.  (This field is only
       relevant if development_directory__style.source_file_symlink is true.)

       For medium-to-large projects, verifying the symbolic links can take as
       long as the build itself.  Assuming the symbolic links are up-to-date
       can be a large time-saving for these projects.  It may be advisable to
       review your choice of DMT in such a situation.

       The aedb(1) command does not consult this preference.  Thus, in most
       situations, the symbolic links will be up-to-date when the build is
       performed.  The only Aegis function which may result in the symbolic
       links becoming out-of-date is the integration of another change, as
       this may alter the presence or absence of files in the baseline.  In
       this situation, the default aeb(1) action is to ignore the user
       preference and the verify symbolic links.

       There are two command line options which modify aeb(1) behavior
       further: the -Verify-Symbolic-Links option says to verify the symbolic
       links; and the -Assume-Symbolic-Links option says to assume the
       symbolic links are up-to-date.  In each case the option over-rides the
       default and the user preference.

       It is possible to obtain behaviour similar to Tom Lord’a Arch by using
       a setting such as:
              development_directory_style =
              {
                  source_file_link = true;
                  source_file_symlink = true;
              };

       It is possible to obtain behaviour similar to CVS by using a setting
       such as:
              development_directory_style =
              {
                  source_file_copy = true;
              };
       There are many more possible configurations of the development_
       directory_style, usually with helpful build side-effects.  See
       aepconf(1) and the Depenedency Maintenance Tool chapter of the User
       Guide for more information.

       The symbolic link command line options and preferences apply equally to
       hard links and file copies (the names have historical origins).

OPTIONS

       The following options are understood:

       -Change number
               This option may be used to specify a particular change within a
               project.  See aegis(1) for a complete description of this
               option.

       -DIRectory path
               This option may be used to specify which directory is to be
               used.  It is an error if the current user does not have
               appropriate permissions to create the directory path given.
               This must be an absolute path.

               Caution: If you are using an automounter do not use ‘pwd‘ to
               make an absolute path, it usually gives the wrong answer.

       -Help
               This option may be used to obtain more information about how to
               use the aegis program.

       -List
               This option may be used to obtain a list of suitable subjects
               for this command.  The list may be more general than expected.

       -Project name
               This option may be used to select the project of interest.
               When no -Project option is specified, the AEGIS_PROJECT
               environment variable is consulted.  If that does not exist, the
               user’s $HOME/.aegisrc file is examined for a default project
               field (see aeuconf(5) for more information).  If that does not
               exist, when the user is only working on changes within a single
               project, the project name defaults to that project.  Otherwise,
               it is an error.

       -REAson text
               This option may be used to attach a comment to the change
               history generated by this command.  You will need to use quotes
               to insulate the spaces from the shell.

       -TERse
               This option may be used to cause listings to produce the bare
               minimum of information.  It is usually useful for shell
               scripts.

       -User name
               This option is used to specify the user who is to develop the
               change.  This option may only be used by a project
               administrator.

       -Verbose
               This option may be used to cause aegis to produce more output.
               By default aegis only produces output on errors.  When used
               with the -List option this option causes column headings to be
               added.

       -Wait   This option may be used to require Aegis commands to wait for
               access locks, if they cannot be obtained immediately.  Defaults
               to the user’s lock_wait_preference if not specified, see
               aeuconf(5) for more information.

       -No_Wait
               This option may be used to require Aegis commands to emit a
               fatal error if access locks cannot be obtained immediately.
               Defaults to the user’s lock_wait_preference if not specified,
               see aeuconf(5) for more information.

       See also aegis(1) for options common to all aegis commands.

       All options may be abbreviated; the abbreviation is documented as the
       upper case letters, all lower case letters and underscores (_) are
       optional.  You must use consecutive sequences of optional letters.

       All options are case insensitive, you may type them in upper case or
       lower case or a combination of both, case is not important.

       For example: the arguments "-project, "-PROJ" and "-p" are all
       interpreted to mean the -Project option.  The argument "-prj" will not
       be understood, because consecutive optional characters were not
       supplied.

       Options and other command line arguments may be mixed arbitrarily on
       the command line, after the function selectors.

       The GNU long option names are understood.  Since all option names for
       aegis are long, this means ignoring the extra leading ’-’.  The
       "--option=value" convention is also understood.

RECOMMENDED ALIAS

       The recommended alias for this command is
       csh%    alias aedb ’aegis -db \!* -v’
       sh$     aedb(){aegis -db "$@" -v}

ERRORS

       It is an error if the change does not exist.
       It is an error if the change is not in the awaiting development state.
       It is an error if the current user is not a developer of the specified
       project.

EXIT STATUS

       The aegis command will exit with a status of 1 on any error.  The aegis
       command will only exit with a status of 0 if there are no errors.

ENVIRONMENT VARIABLES

       See aegis(1) for a list of environment variables which may affect this
       command.  See aepconf(5) for the project configuration file’s project_
       specific field for how to set environment variables for all commands
       executed by Aegis.

SEE ALSO

       aeb(1)  build a change

       aecd(1) change directory

       aecp(1) copy files into a change

       aed(1)  find differences between a change and the baseline

       aedbu(1)
               undo the effects of aedb

       aede(1) complete development of a change

       aemv(1) rename a file as part of a change

       aenc(1) add a new change to a project

       aend(1) add a new developer to a project

       aenf(1) add new files to a change

       aent(1) add a new test to a change

       aepa(1) modify the attributes of a project

       aerm(1) add files to be deleted to a change

       aet(1)  run tests

       aepattr(5)
               project attributes file format

       aeuconf(5)
               user configuration file format

COPYRIGHT

       aegis version 4.21
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
       2000, 2001, 2002, 2003, 2004, 2005 Peter Miller; All rights reserved.

       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/