vupdate(1)

Name

vupdate - update the imports of a Vesta model

Synopsis

vupdate [ options ] [ model ]

Contents

Description

vupdate updates the imports of the named model so that all imports are to the latest package versions. Only those imports of models outside the package are updated. If no model is specified, it defaults to ".main.ves".

Ordinarily, vupdate replaces the existing model with the updated version. If -no-action is specified, if the updated model is identical to the existing one, or if errors occur, the existing model (and its parent directory) are left untouched.

To prevent the import of a model from being considered for updating, precede the model's pathname by a /**noupdate**/ or /**NOUPDATE**/ pragma.

When the import being updated is to a model in a checkout session, the import is updated to point to the latest main version within the package (or branch) if such a version exists, or to the latest version in the checkout session otherwise. This behavior can be overridden using to -to-checkout switch below. Also see the -advance-checkout switch if you would like checkout sessions to be advanced.

The model argument is resolved according to the rules for import clauses as specified in The Vesta-2 Software Description Language. In particular, if model is not an absolute path, it is interpreted relative to the current working directory. If model names a directory, the string "/build.ves" is appended to it; otherwise, if it does not end in ".ves", that extension is appened to it.

Options

vupdate accepts the following command-line options:

-no-action or -n
No action. Do not rewrite model, but print out what imports would be updated. Do not advance any checkout sessions. A warning is printed at the end of the output indicating that no action was taken. This option is mutually exclusive with the -query and -silent options.

-query or -q
Query mode. You will be queried on each potential update. To accept the update, type "y" and hit <ENTER>. If any other input is supplied, the import is not updated. This option is mutually exclusive with the -no-action and -silent options.

-silent or -s
Silent mode. By default, the name of each model requiring changes and the old and new versions of all updated imports are printed. This option supresses that output. This option is mutually exclusive with the -no-action, -query, and -verbose options.

-update-local or -r
Update local models recursively. By default, vupdate revises only the named model. If -update-local is specified, then any local models imported directly or indirectly by model are updated recursively. An imported model is considered to be local if it is specified by a relative pathname.

-advance-checkout or -a
Advance your imported checkout sessions. If -advance-checkout is specified, then whenever the model imports from a checkout session that belongs to you (including new checkout imports created by the -to-checkout option), vupdate will invoke vadvance(1) to attempt to advance the session before searching for the session's highest version.

-update-checkout or -c
Update models in your imported checkout sessions recursively. If -update-checkout is specified, then any models imported directly or indirectly from checkout sessions that belong to you are updated recursively (including new checkout imports created by the -to-checkout option). The sessions are then advanced as with the -advance-checkout option.

-update-all or -u
Sets both the -update-local and -update-checkout options.

-verbose or -v
Verbose mode. By default, if a model would not require any changes, its name is not printed. If -verbose is specified, the names of all processed models are printed. This option is mutually exclusive with the -silent option.

-limit name or -l name
Limit which imports will be updated. Only imports with a full pathname containing name will be updated. If multiple -limit clauses are specified, only those pathnames containing all specified names are updated. (For example, combining -limit src.dec.com with -limit repos would cause only imports containing both src.dec.com and repos to be updated.)

-limit-checkout or -L
Only update imports for checkout sessions. Equivalent to -limit /checkout/.

-to-checkout or -t
Allow imports to be updated to point to models in new checkout sessions. This both allows checked in versions to be updated to checked out versions, and allows old checkout session references to be updated to refer to new checkout sessions. This option is mutually exclusive with the -attr option.

-only-mine or -m
When updating an import, don't modify it to point to a checkout session belonging to another user. An import may be updated from another user's checkout session to a checked in version. An import may be modified to point to a checkout session belonging to the user running vupdate. If an import currently refers to a checkout session belonging to another user which has not been checked in, it won't be updated.

-attr attr-spec or -A attr-spec
Selective update. By default, vupdate updates each import to the latest relevant version. If -attr is specified, each import is updated to the latest version whose attributes match attr-spec. This option is mutually exclusive with the -to-checkout option.

The attr-spec should be a string according to the following grammar: 

attr-spec  ::= attr-name [ val-select val-list ]
attr-name  ::= String
val-select ::= `:' | `^'
val-list   ::= String | String `,' val-list
There are three cases:

  1. When attr-spec is simply an attr-name, a given package version matches the spec if it simply defines the attribute named attr-name.

  2. If attr-spec takes the form attr-name:attr-list, then a given package version matches the spec if it binds the attribute attr-name to a set of values at least one of which is named in attr-list.

  3. If attr-spec takes the form attr-name^attr-list, then a given package version matches the spec if it does not define the attribute attr-name, or if it binds the attribute attr-name to a set of values none of which is named in attr-list.

-parse-errors-stop or -e
Any trouble understanding the version imported or choosing a new version will be treated as a fatal error, causing vupdate to stop and leaving model unmodified. vupdate can always understand simple integer versions which are the norm, but can have difficulty with non-integer versions. Without this option, vupdate will issue a warning about each import it can't understand and leave it unmodified in model, proceeding on to update subsequent imports.

Restrictions

vupdate assumes that packages and models are structured in certain ways. Most of these restrictions are enforced by the repository tools. In addition to the obvious requirement that the models are syntactically legal according to the Vesta-2 Software Description Language, vupdate also makes the following assumptions:

Examples

One typical use is to test what imports would be updated using the -n option, like this: 

$ vupdate -n -r -v
/vesta-work/heydon/vimports/.main.ves
     /vesta/src.dec.com/common/std_env/42/build.ves
  -> /vesta/src.dec.com/common/std_env/49/build.ves

/vesta-work/heydon/vimports/build.ves
/vesta-work/heydon/vimports/src/progs.ves
/vesta-work/heydon/vimports/src/docs.ves
/vesta-work/heydon/vimports/src/lib.ves
WARNING: Nothing updated at your request!
The package can then be updated normally: 
$ vupdate
/vesta-work/heydon/vimports/.main.ves
     /vesta/src.dec.com/common/std_env/42/build.ves
  -> /vesta/src.dec.com/common/std_env/49/build.ves
Query mode can be used to selectively update a model's imports: 
$ vupdate -q
/vesta-work/heydon/release/.main.ves
     /vesta/src.dec.com/common/cxx/checkout/14/82/build.ves
  -> /vesta/src.dec.com/common/cxx/checkout/14/83/build.ves
  Update this import (y/n)? y

     /vesta/src.dec.com/common/std_env/48/build.ves
  -> /vesta/src.dec.com/common/std_env/49/build.ves
  Update this import (y/n)? n
The following example shows a case where a checkout session has been updated to refer to a checked-in version of the package: 
$ vupdate
/vesta-work/heydon/basics/.main.ves
     /vesta/src.dec.com/c/libc/checkout/4/1/build.ves
  -> /vesta/src.dec.com/c/libc/7/build.ves
By adding the -to-checkout option, a checked in version can be updated to a current checkout session: 
$ vupdate -to-checkout
/vesta-work/schalk/std_env/.main.ves
     /vesta/shr.dec.com/common/cxx/4/build.ves
  -> /vesta/shr.dec.com/common/cxx/checkout/5/6/build.ves
The following example will update imports only to package versions that define an "approved" attribute: 
$ vupdate -attr approved
The following example will update imports only to package versions that define a "status" attribute to have a value of either "passed" or "released": 
$ vupdate -attr status:passed,released
The following example will update imports only to package versions that do not define a "status" attribute whose value is "buggy": 
$ vupdate -attr status^buggy

Configuration

The following values are obtained from the [UserInterface] section of the Vesta configuration file (vesta.cfg).

TempDir
Name of a Vesta mutable directory that can be used for temporary file storage. Ordinarily set to /vesta-work/.tmp.

Bugs

See Also

repos-ui(1), vimports(1), vlatest(1)

Author

Allan Heydon (heydon@src.dec.com) 

Created on Tue Jul 15 17:01:30 PDT 1997 by heydon
Last modified on Tue Nov 13 12:51:05 EST 2001 by ken@xorian.net   
     modified on Thu Jul 13 18:32:31 PDT 2000 by mann   
     modified on Mon Jan 31 15:03:33 PST 2000 by heydon 
     modified on Fri Feb 12 23:15:25 EST 1999 by schalk@cadtls.hlo.dec.com
     modified on Fri Feb  6 16:22:42 PST 1998 by yuanyu
This page was generated automatically by mtex software.