API review

Proposer: Eric Berger

Present at review:

• Radu, Ken, Jeremy, Brian, Tully, Rob, Morgan

Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

Meeting agenda

To be filled out by proposer based on comments gathered during API review period

Eric's suggested API:

Here's my shot at a full rosinstall API.  Very similar to what we went
over in the ROS meeting.
Let me know if anything in here looks wrong.

SYNTAX
===

rosinstall [options] INSTALL_PATH [URI]
[URI] argument is only optional together with --update option

options:
-u or --update (URI is optional only when using --update)
-s setup_file or --setup=setup_file (uset setup_file to specify ROS environment)
-o or --overlay  (bake current ROS environment into setup.sh)
-n or --nobuild

BEHAVIOR:
===

Basic invocation:
 Finds config file at URI (web or file.  rosconfig syntax, currently
supporting only svn: entries)
 Writes value of URI into file .rosinstall_source_uri
 Checks out all components to $INSTALL_PATH from source control
(currently just SVN)
 Figures out proper environment (ROS_ROOT, etc.)
 Creates setup.sh file in $INSTALL_PATH (see below for details on what
goes here)
 Calls "make core_tools" in ros stack if ros stack was installed (not if ROS_ROOT
was gotten from environment variables), unless -n or --nobuild is
specified
 Prints out line about "source setup.sh to set up your environment, or
set up to call it from your .bashrc if you want"
 Prints out advice about using rosmake to build any packages they want


Update
 Doesn't change the setup.sh file (possibly verifies it?  Not
necessary in first version)
 with SVN, this will run basically the same logic (run checkouts in
the same place, which will act as updates)
 Uses value of $INSTALL_PATH/.rosinstall_source_uri as config file
(unless --config is specified, which over-rides and writes out
.rosinstall_source_uri)
 Warns if URI is different from $INSTALL_PATH/.rosinstall_source_uri
and asks for confirmation
 Warns if .rosinstall_source_uri doesn't exist and asks for
confirmation / recommends fresh installation.
 Re-runs make in "ros" directory unless -n option is specified


ROS stack determination and setup.sh
===
No options:

If the config file includes a stack with local name "ros", then that
is treated as the ROS_ROOT, and any ROS environment variables already
set are ignored.
setup.sh would include:
 set ROS_ROOT to $PATH/ros, set all other ROS variables explicitly so
that this creates a full ROS environment

If the config file does not include a stack with "ros", and -o or -s
were not specified, then prompt user for what to use as ROS_ROOT.
No stack named "ros" found in config file
Would you like to infer ROS_ROOT from your existing ROS environment? [Y/N] y -> same as -o option
Would you like to base your ROS environment on an existing setup file? [] -> same as -s option

-s option:

If the -s option is used, the file "setup_file" is assumed to be a
file that if sourced will set up the ROS environment properly.  Error
if -s is specified but config includes ROS.
setup.sh would depend on $setup_file to do the setup and include just:
 source $setup_file
 ROS_PACKAGE_PATH=$PATH/whatever:$ROS_PACKAGE_PATH


If the -o option is used, make sure the environment defines a
ROS_ROOT, ROS_PACKAGE_PATH PYTHONPATH, etc. Assume that those define
the environment within which these package should be run should be
run, but that setup.sh should do all the setup to make the environment
look like this itself.
Error if -o option is specified but config includes ROS
setup.sh would include:
 Setting ROS_ROOT based on the value of $ROS_ROOT active when
rosinstall was run
 Setting ROS_PACKAGE_PATH based on prepending the new directories to
the $ROS_PACKAGE_PATH that already existed
 Making sure that $ROS_ROOT/bin is in the path, etc.


ERRORS (partial list)
===
Error if -o and -s are both specified.
Error to specify -o or -s together with -u
Error to run rosinstall with no URI unless -u is specified (install
doesn't ever use ,ris=

Conclusion

Package status change mark change manifest)

• Action items that need to be taken.

• Major issues that need to be resolved

Changes to be made to the API:

• Replace interaction with printing likely next steps to screen

API APPROVED.

---