Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
aegis -Develop_Begin(1)	    General Commands Manual    aegis -Develop_Begin(1)

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 automati-
	cally; below the directory specified in	the default_development_-
	directory field	of aeuconf(5), or if not set below the directory spec-
	ified 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" move to S2.w T1:
	spline -> left 0.75 then up 1 then to S1.w " develop" ljust " begin"
	ljust "	undo" ljust at T1.c - (0.75,0)

   Notification
	The develop_begin_command in the project configuration file (see aep-
	conf(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	deter-
	mine 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 filesys-
	tems 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 en-
	vironments.

	If your	development directories	are routinely on a Linux UMSDOS
	filesystem, you	would probably be better off setting dos_filename_re-
	quired = 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 develop-
	ers.  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 de-
	velopers.  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	aep-
	conf(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 execu-
	tion 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 rele-
	vant 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	pref-
	erence and the verify symbolic links.

	There are two command line options which modify	aeb(1) behavior	fur-
	ther: the -Verify-Symbolic-Links option	says to	verify the symbolic
	links; and the -Assume-Symbolic-Links option says to assume the	sym-
	bolic 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 aep-
	conf(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	appro-
		priate 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	envi-
		ronment	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 sin-
		gle project, the project name defaults to that project.	 Oth-
		erwise,	it is an error.

	-REAson	text
		This option may	be used	to attach a comment to the change his-
		tory 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 administra-
		tor.

	-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.  De-
		faults 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 op-
	tional.	 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	inter-
	preted 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	"--op-
	tion=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	er-
	rors.

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.25.D510
	Copyright (C) 1991, 1992, 1993,	1994, 1995, 1996, 1997,	1998, 1999,
	2000, 2001, 2002, 2003,	2004, 2005, 2006, 2007,	2008, 2009, 2010,
	2011, 2012 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:	 pmiller@opensource.org.au
	/\/\*		  WWW:	 http://miller.emu.id.au/pmiller/

Reference Manual		     Aegis	       aegis -Develop_Begin(1)

NAME | SYNOPSIS | DESCRIPTION | ADMINISTRATOR OVERRIDE | SYMBOLIC LINKS | OPTIONS | RECOMMENDED ALIAS | ERRORS | EXIT STATUS | ENVIRONMENT VARIABLES | SEE ALSO | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=aedb&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help