bsubmit(1) UNIX Programmer's Manual bsubmit(1)
NAME
bsubmit - submit files to latest or to a shared sandbox
SYNOPSIS
bsubmit [-v -q -info -auto -auto_out -auto_ci -nolog] [-b
target] [sb opts] [local opts] [log opts]
recover opts | -all | file ...
sb opts: [-sb sandbox] [-set setname] [-rc rc-file] [-sb_rc
sb-rc-file]
local opts:
[-local_co [backing lock]]
log opts: [-fn "full name"] [-defect number] [-log logfile]
recover opts:
-resub time [-count count] [-date date]
[-no_merge -no_build_ci -no_build_co]
bsubmit -usage
bsubmit -rev
FLAGS
-v Prints out information about what bsubmit is doing
while it is doing it.
-q Passes the quiet flag to the bcs commands it calls to
reduce the amount of information being printed.
-info
Indicates what bsubmit would do without actually doing
it. Can be used with -v for additional output.
-auto
Whenever there is a default answer to a prompt, use it
without waiting for user input.
-auto_out
The default behavior of bsubmit is, after completing
the submission, to prompt the user to outdate the
file(s) from the local set. Outdating a file removes
the local copy of the file from the set as well as
removing any reference to the file from the local BCS
logs. This option is used if the user does not want to
get the prompt for outdating, in other words, the out-
dating occurs automatically. To be sure that this
option is really meant, it requires that both the -auto
and the -auto_out options are set, otherwise bsubmit
will still prompt the user. If this option is used
with the -local_co backing and -auto options, bsubmit
Printed 1/23/91 5/4/90 1
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
will automatically outdate the branch of each file
before checking out a new revision from the backing
tree.
-auto_ci
Normally submitted files are already checked-in, how-
ever, if they are not, bsubmit will offer the user the
option of running bci. This option causes bsubmit to
automatically check-in any file which needs it.
-nolog
Check-ins normally assume each file will have a log.
If this option is given, bsubmit will pass the -nolog
option on to bci. -nolog and log submission should NOT
be combined.
-b target
Changes the build or shared sandbox the files will be
submitted to. The default is the latest build. If a
shared sandbox is chosen, the full path must be entered
starting with "/".
-all To submit all the files in the set, use this option.
If this option is not chosen, the user must list the
files to submit. The files in the set are listed in
the sandbox's source directory in the file .BCSset-
user_setname.
-usage
Prints a brief usage message.
-rev Prints the revision information.
sb opts:
-sb sandbox
Name of the sandbox to use if it is not the current
sandbox. If this option is not used, the sandbox will
be determined by the environment variable SANDBOX or,
if that is not set, by the user's default sandbox.
-set setname
Name of the set to use if it is not the current set.
If this option is not used, the set will be determined
by the environment variable BCSSET or, if that is not
set, by the sandbox's default set.
-rc rc-file
Provides the path and name of the user's rc file to use
instead of the default file ${HOME}/.sandboxrc. If
this option is not used, the default rc file will be
used.
Printed 1/23/91 5/4/90 2
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
-sb_rc sb-rc-file
Provides the path and name of the sandbox's rc file to
use instead of the default file sandbox/rc_files/local.
If this option is not used, the default sandbox's rc
file will be used.
log opts:
-fn full name
String holding the user's full name, for example,
"Suzie Que". The name will have to be quoted to con-
tain the space. If this option is not used, bsubmit
will prompt the user for this information before creat-
ing the log message.
-defect number
The number of the defect which this submission applies
to. If this option is not used, bsubmit will prompt
the user for this information. This field can contain
a single number, multiple numbers, or be left empty.
-log logfile
Replaces the standard logfile with the one given and
enters it without putting the user in an editor. Nor-
mally, bsubmit takes the bci log and has the submitter
edit to get the submission log. This option takes the
path and name of a file to use instead of the bci log.
For relative paths, bsubmit starts its search from the
source directory of the sandbox.
local opts:
-local_co
Checks a revision of the newly submitted file(s) out
into the local set. The default behavior of bsubmit is
to outdate submitted files. This option changes that
so the files are checked out after submission. There
are two arguments which this option accepts: backing
and lock. If neither option is given, the files checked
out will come from the submitter's branch and will be
unlocked. WARNING: because this option can accept two
arguments, the syntax can be ambiguous. For example,
bsubmit -local_co build myfile1 myfile2 will be inter-
preted as attempting to give -local_co two arguments:
build and myfile1. To avoid this, either another "dash"
option can be placed between the -local_co option and
the list of files, bsubmit -local_co build -v myfile1
myfile2 or the -local_co option can be placed last,
bsubmit myfile1 myfile2 -local_co build.
backing
If this argument is given to the -local_co option, the
Printed 1/23/91 5/4/90 3
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
files checked out will come from the sandbox's backing
tree. In order to get this result, the user's branch
of the files will be outdated before the check-out.
NOTE: the checked-out version does not come from the
build which is being submitted to unless the user is
backed by that build.
lock If this argument is given to the -local_co option, the
files will be checked out locked instead of just
unlocked. This argument works both with or without the
build argument.
recover opts:
-resub time
This option is used to continue a bsubmit which has
been interrupted or failed. To identify which submis-
sion to retry, bsubmit uses the environment variable
USER and the time the submission began. bsubmit
attempts to give the user the time information before
it exits a failed submission. The time and user name
form the name of the tracking file the resubmission
will be based on. These files, found under
/project/osc/build/latest/logs, indicate to bsubmit how
far in the process the submission got before it failed.
bsubmit will use this information to skip the steps
which have already been completed. The -count option,
described below, provides a method for picking up the
process in the middle of a step. When doing a resub-
mission, the list of files to submit is NOT given as
part of the -resub option. The files to resubmit are
retrieved from the hold log,
/project/osc/build/latest/logs/bsubmit.hold . Other
options, such as -auto and -v work with -resub includ-
ing the -info option to preview the resubmission.
-count count
For purposes of resubmitting, the submission process is
broken into five steps which the tracking file records
as each succeeds. When the -resub option is used, the
steps which have been completed are skipped. When the
failure occurs within a step rather than in-between two
steps, the -count option provides a method for telling
bsubmit where to resume the submission. The count in
the -count option is the number of files which were
successfully processed in the step which failed. For
example, if after successfully merging five files, the
merge failed on the sixth, the line bsubmit -resub time
-count 5 would restart the submission in the merge
step, skipping the first five files.
-date date
Printed 1/23/91 5/4/90 4
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
Like the time and USER, the date is used to identify
the submission to be resubmitted. Since submissions
and resubmissions are normally made on the same day,
today's date is used by default. This option is used
to override this default. The form of the date is:
M/D/YY where M is the number of the month, D is the
number of the day of the month, and YY is the two digit
representation of the year.
-no_merge
Prevents the submitted files from being merged with the
build. The state of this option is normally set by -
resub when it reads the tracking file, however, the
user can explicitly tell bsubmit to skip this step by
using this option.
-no_build_ci
Prevents the merged files from being checked into the
build. The state of this option is normally set by -
resub when it reads the tracking file, however, the
user can explicitly tell bsubmit to skip this step by
using this option.
-no_build_co
Prevents the checked-in files from being checked-out
onto the build. The state of this option is normally
set by -resub when it reads the tracking file, however,
the user can explicitly tell bsubmit to skip this step
by using this option.
bsubmit submits files to the latest build area for the set
LATEST or to a shared sandbox. If it is submitting to
another sandbox, that area must have a shared set and allow
the user to write into it.
DESCRIPTION
bsubmit is designed to take all the steps required to submit
a file and combine them into a single program. A user can
see what those step are by using the -info option which
prints out the steps without actually doing them. Adding
the -v gives even more output.
The primary pieces of information that bsubmit needs from
the user are the build to submit to and the list of files to
submit. If no build is specified, the latest build is used
with its default set: LATEST. Other options bsubmit takes,
such as checking the files out onto the user's local set
after submitting, can be used but are not required.
Like all the sandbox and BCS tools, bsubmit requires the
user to have a sandbox and a set to work from. If the
Printed 1/23/91 5/4/90 5
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
sandbox and set are not specified, bsubmit will use the
default settings. If it cannot find a sandbox or set, it
will exit with an error message.
The list of files to submit can be specified in one of three
ways but each relative to the source directory in the sand-
box. First, if the file is given with an absolute path,
i.e. it begins with a '/', bsubmit searches that path from
the sandbox's source directory down. Since the path was
absolute, if the file isn't found at that location, bsubmit
exits with an error.
Second, if the path isn't absolute, bsubmit will look in the
directory the user is in, assuming that directory is under-
neath the sandbox's source directory. Finally, it will look
in the set's default directory as specified in the file
rc_files/sets. It does this relative to the source direc-
tory.
Thus a user can specify just the name of the file if it is
either in the current directory or in the set's default
directory; otherwise, the path to the file needs to be
given.
A fourth way the user can specify the files to submit is to
give the -all option. bsubmit will use all the files listed
in .BCSset-user_setname as the list of files if this option
is used.
If the files are not already checked-in, bsubmit will offer
to do this step.
Steps for Submission
bsubmit uses the bcs commands to do most of the work on the
user's set and the set being submitted to. The following
list enumerates the major steps bsubmit goes through to sub-
mit a file. Each step is discussed in terms of the build
latest but applies equally to a shared sandbox with a shared
set. The steps bsubmit goes through to submit a file to
latest are:
Check to see that none of the files to be submitted are
checked out or locked
If they are checked-out, offer to check them in
Remove any extraneous locks on the local set's version of
the files
Check to see if there is a lock on the latest version of
any file
If someone has a lock on that version, print the informa-
tion and exit
Hold each of the files being submitted, i.e. do not let
anyone else attempt to submit one of these files
Printed 1/23/91 5/4/90 6
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
Merge the local and latest revisions of each file
Check the files in to latest
Check the files out onto the latest build
Prompt the user for log information and add this to submis-
sion log
Update latest's snapshot file
Release the hold on the files
The User's Set
After a file has been submitted, bsubmit can do a number of
things with the branch of the file in the user's set. The
default case is to prompt the user to outdate the file. The
benefit of outdating the file is that the next time the file
is checked out, the revision will come from the backing
tree. If the file isn't outdated, the next revision will be
a continuation of the branch of the file that was just sub-
mitted. If there is more than one developer working on the
file, the next time a developer submits the file, the merge
is usually simpler if the file is taken off the backing tree
rather than a continuation of the user's branch.
Of course, the user may not want to outdate the file, there-
fore bsubmit prompts the user before it does any outdating.
If the user answers "no" to outdating, a copy of the merged
version of the file will be left in the local set. This
version is a read-only copy and is not checked out.
Besides the user's response, two options can affect outdat-
ing: -auto_out and -local_co.
-auto_out, if used in conjunction with -auto, will eliminate
the prompt, i.e. it will automatically outdate the file
list. The purpose behind this option is to provide a com-
pletely non-interactive submission when that is desirable.
The other option, -local_co, check outs each file into the
user's set. The revision in the developer's set will be the
top of the developer's branch for that file. The default
check out is unlocked but this can be overridden with by
using the lock argument with the -local_co option. In both
these cases, the files will not be outdated.
Finally, to check-out the files from the backing tree
instead of the user's branch, the backing argument can be
used with the -local_co option. To get this revision, the
files are outdated before they are checked out. The user is
prompted before outdating unless the -auto and -auto_out
options are used.
Logs
After the files have been submitted, bsubmit updates two
Printed 1/23/91 5/4/90 7
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
logs; the bsubmit.log and the SNAPSHOT file. A shared sand-
box does not have to have these logs so, if they are not
updated, only a warning is issued. However, all submission
to latest must finish by successfully updating these logs.
The bsubmit.log is located in
/project/osc/build/latest/logs/bsubmit.log and contains a
running history of who submitted which files when and what
the major changes to the files were. bsubmit prompts the
user for some of this information and puts the user in an
editor to write the detailed description of the submission.
There are command line options which will give bsubmit this
information so the user doesn't have to wait for prompts.
The user also gets a copy of the submission log which he is
asked to mail to interested people.
The second file bsubmit updates is the SNAPSHOT file which
contains a list of the files in latest and their current
revisions. After a submission, this file must be edited to
include any new files and to change the revision number of
existing ones. bsubmit does this without user interaction.
Recovery
bsubmit attempts to keep track of it progress so, if there
is a failure, it can aid the user in recovering. Each sub-
mission is comprised of six major steps:
check for locks
merge
check-in to latest
check-out onto latest
update the logs
process the submitter's set
The resubmission process concerns itself with the first five
steps as the user can more easily recover from errors in
processing her local set without using bsubmit.
The tracking files indicate which, if any, of the first four
steps have been completed; if all five have been completed,
there is no need for resubmitting. It uses this information
to skip as many of the steps as it can. The user can
further aid the recovery by using the -count option to indi-
cate how many files within a step were successfully pro-
cessed. If the check for locks and merge steps were com-
pleted and three files were checked-in before the failure,
the command bsubmit -resub time -count 3 restarts the sub-
mission with the fourth file being checked-in.
bsubmit has three additional options which can be given to
explicitly skip steps two through four: -no_merge,
-no_build_ci, and -no_build_co. Since the state of each of
Printed 1/23/91 5/4/90 8
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
these is normally retrieved from the tracking file, the user
usually does not set these.
Tutorial
As part of the tutorial for the ODE Development User's Guide
and to provide an area for practice submissions, and submis-
sion containing a file in the directory /usr/local/tutorial/
will not update the SNAPSHOT file. In this way, nothing
submitted to that directory will show up in builds or be
released.
EXAMPLES
bsubmit -info /usr/bin/wakeup.c
Indicate what would happen if the file
/usr/bin/wakeup.c in the current sandbox and set was
submitted to latest, but don't actually submit it.
bsubmit -v ./lbin/*
Submit all the files in the current sandbox which are
under the source tree in lbin to latest and use the
verbose mode. For this command to work successfully,
all the file under lbin would need to be in the current
set.
bsubmit -auto -auto_out -all
Submit all the files in the current sandbox and current
set to latest. Whenever there is a default answer to a
prompt, use it without stopping for user input. After-
wards, automatically outdate the files in the set.
bsubmit -back /project/osc/sandboxes/loader ld -
local_co lock
Submit the file ld to the shared sandbox
/project/osc/sandboxes/loader. Submissions to shared
sandboxes always use the sandbox's default set. After
submitting, check-out, locked the user's set's revision
of the file.
bsubmit -v -auto -resub 9:08 -count 1
Resubmit the same submission begun by this user a 9:08
a.m. today. The number of steps completed will be
determined from the file
/project/osc/build/latest/logs/9:08.user The user has
specified that the first file has already completed the
next step, so begin with the second file.
FILES
/usr/tmp/rcfile
bsubmit creates a temporary rc file for the build or
sandbox it is submitting to.
Printed 1/23/91 5/4/90 9
bsubmit(1) UNIX Programmer's Manual bsubmit(1)
/sandbox/rc_files/shared
normally contains the location of the source_base.
This can be overridden on the command line, in the
user's rc file, or in the /sandbox/rc_files/local file.
/project/osc/build/latest/SNAPSHOT
contains the current revision of each file in latest.
/project/osc/build/latest/logs/trackingfiles
files which track the progress of each submission.
/project/osc/build/latest/logs/bsubmit.log
file containing the log entries for every submission.
/project/osc/build/latest/logs/bsubmit.hold
file containing the list of files which are held, i.e.
currently being submitted. A file can only be held by
one submitter at a time.
EXIT VALUES
bsubmit returns '0' upon successful completion, '-1' other-
wise.
RELATED INFORMATION
bcs(1), bci(1), bco(1), bmerge(1), bstat(1), latest(5),
sandbox(5) sandboxrc(4).
PLANNED ENHANCEMENTS
There are a number of enhancements planned for bsubmit
including a method for mailing out the log information to
selected groups.
Printed 1/23/91 5/4/90 10