diff --git a/doc/questions.md b/doc/questions.md new file mode 100644 index 0000000..adb185c --- /dev/null +++ b/doc/questions.md @@ -0,0 +1,55 @@ +# ros-get questions + +- *1. where do these packages come from??* + - Would be the ros-distro story, but needs a good place in the manual. + - perhaps an example and a eference to the REP. + +- *2. which branch?* + - ``ros-get update`` does what wrt branches? + - should it do other things with branches too? (make them, remove them, switch between them, push them, fetch/pull them, etc) + - *3. are all branches updated?* Assuming you can have some repos using a different branch, are these updated too, or is that configurable, or? + +- *4. is this true?* + - ``ros-get list`` seems to list the top-level packages? + - *5. get other information?? how??* + - can it provide other lists (manually installed as required versus installed as dependency, for example) + - can you get packages that nobody needs any more? + +- ``ros-get remove`` considerations: + - *6. really? what if it is needed by some other package??* Can you remove a package that is needed as dependency? + - *7. is a package removed automatically by itself when it is not required any more??* is that desired? + - *8. if so (if automatically removed), can you avoid that?* + +# tue-tools differences that may be nice to add + +- ``tue-checkout BRANCH`` switch repositories to a branch (would fit in ``ros-get update``? or perhaps ``ros-get branch``?) +- ``tue-get list-installed`` (ros-get list functionality?) +- ``tue-get dep [PKG]`` list dependencies of PKG (ros-get list functionality?) + - list upto some depth D? + +- ``tue-git-status`` list branch/revision/status of all repos (does not exist yet?) + +- ``tue-set-git-remote`` do remote repo management, eg at robocup, add new 'amigo' upstream? + - tue tools seem to modify origin, which seems a bit hackish, perhaps construct a way to switch local master between remote masters? + +# tue-tools without any clue what it is or does. +- tue-data (no idea wht it is) +- tue-dashboard (no idea what it is) + +# tue-tools differences that we may not want in ros-get +Functionality listed here should either be created by other means, for example as a command, or get discarded + +- ``tue-get --release`` build Debian package`` (looks catkin-ish) + +- ``tue-make`` / ``tue-make-dev`` / ``tue-make-dev-isolated`` / ``tue-make-system`` + - probably provided by catkin already? + +- ``tue-revert`` and ``tue-revert-undo``. + +- ``tue-create ros-kpg PACKAGE_NAME [DEPENDENCY1 DEPENDENCY2 ..]`` code generator for ROS package boiler-plate +- ``tue-create cpp-class CLASS_NAME PROJECT SUPER_CLASS`` code generator for cpp class. +- ``tue-env cd`` woud at least be bash. Likely also exists as ``roscd``? +- time-zone commands +- apt-get-proxy +- ``tue-save-map`` + diff --git a/doc/userman.md b/doc/userman.md new file mode 100644 index 0000000..68502d4 --- /dev/null +++ b/doc/userman.md @@ -0,0 +1,226 @@ +# *Ros-get* user manual +The *ros-get* software aims to simplify development of (ROS-based) software by +automating handling of Catkin workspaces and packages therein. + + +## Catkin workspace +The *ros-get* software builds on Catkin workspaces, this section briefly +explains how such workspaces work. + +Global layout of a Catkin workspace is +(see also [Catkin workspaces](wiki.ros.org/catkin/workspaces)) + +- ``ws`` root directory of the workspace. + - ``src`` Source code of the work space, each package has its own + directory, Catkin constructs a CMake setup directly in ``src`` to build + all the packages in the right order. + - ``build`` Temporary space for ``CMake`` to build the packages from ``src``. + - ``devel`` Built targets are placed here before installation. + - ``system`` Installed targets are placed here. + +Both ``devel`` and ``system`` are known as *result* spaces, as they contain +results of the build process. + +To use a Catkin workspace, you source the setup script in one of the result spaces. +This sets a number of environment variables, which guide the various Catkin +tools to that workspace. + + +# *ros-get* tools +The Catkin tools handle building of all packages in the work space, such that +packages are only built if all packages that it needs are already available. + +The *ros-get* tools aim to simplify creating a Catkin workspace, +populating it with all the packages that you need from external repositories, +and keeping the packages up-to-date with respect to changes in the +repositories. Also, it has functionality for keeping several workspaces. + +Commands related to handling workspaces are +- *ws-create*: Create a new workspace. +- *ws-switch*: Switch to a workspace. +- *ws-save*: Saves the current workspace. +- *ws-list*: List all saved workspaces. +- *ws-locate*: Prints the path to the current workspace. + +Commands related to handling packages in a workspace are +- *install*: Install packages. +- *update*: Update all packages in the workspace to the latest version. +- *list*: List all installed packages. +- *remove*: Remove packages. + +First, handling workspaces is discussed. Next, handling packages in a single +workspace is considered. + + +## Handling workspaces +In the ideal case, you have only one Catkin workspace, but as development +progresses you may run into the situation that having more Catkin workspaces +would be useful. For example, when working on a second robot, or making large +changes for example to prepare for a new ROS distribution. + +Ros-get has a number of commands to simplify managing several Catkin +workspaces, as explained below. + + +### *ros-get ws-create* +Creation of a new workspace is one of those things you don't do often enough +to remember all the details. *Ros-get* gives you a command to do this, and also +adds the new workspace in the list of workspaces know by *ros-get*, thus +allowing you to use it with the other workspace commands. +The command is + + ros-get ws-create [--name NAME] DIRNAME [EXTEND] + +The ``DIRNAME`` is the name of an existing (but empty) directory that should +be used as a new Catkin workspace. It creates all the administrative files and +directories in it, using the workspace you have currently selected +with Catkin or *ros-get* as parent. Alternatively, you can specify the parent +workspace that should be used as a second ``EXTEND`` argument. Doing the latter also +has the advantage that you are sure how the new workspace is set up. + +Each workspace has a name, which is used with all the workspace commands of +*ros-get*. The name of the new workspace is the same as ``DIRNAME`` (the +directory name of the new workspace) by default, but this can be overridden +with the ``--name`` option. + + +### *ros-get ws-switch* +With more than one workspace, it is useful to be able to switch between them. +In *ros-get*, that is done with + + ros-get ws-switch NAME + +where ``NAME`` is the name of the workspace to switch to. +(See the *ws-list* command below if you don't remember the workspace name.) + +### *ros-get ws-list* +To get an overview of your available workspaces, use the + + ros-get ws-list + +command. + +### *ros-get ws-locate* +When you are curious which *ros-get* workspace you have currently selected, +you can ask *ros-get* about it by typing + + ros-get ws-locate + +It prints the path to the current workspace. This command is also useful for +programmatically accessing your current workspace. + +### *ros-get* save +To enable *ros-get* for an already existing Catkin workspace, use the +``ws-save`` command, as in + + ros-get ws-save [--name NAME] PATH + +with ``PATH`` being the root directory of the Catkin workspace. By default, +the name of the new workspace is derived from the directory name. You can +override it by using the ``--name`` option. + + +## Handling packages +In a single Catkin workspace, the software is organized as a collection of packages +(see http://wiki.ros.org/Packages). Catkin takes care of being able to build +and combine the packages to a functioning piece of software. However, there +are more things to consider with each package. + +Packages may come from several sources, and typically depend om other packages +to do their work. Some packages are updated rarely, while others are in more +early development, and get modified a lot. As a result, packages in +a workspace need to be synchronized with their source. Such synchronization +may in turn cause that dependencies between packages change, causing further +changes in the workspace. The latter is what *ros-get* aims to handle using +the commands listed below. + + +### *ros-get install* +To add new packages to the workspace, use the ``install`` command. + + ros-get install PKG1 PKG2 ... + +The listed packages get added to the workspace. If they require other packages +that are not yet available, those are added as well. + +**1. where do these packages come from??** +(would seem it needs more introduction of how ros-get works?)` + + +### *ros-get update* +Once you installed a number of packages in your workspace, you can start +working on them, changing them as needed. Likewise, others may update other +packages in your workspace. +Making your own changes available is hard to automate, as it involves a lot of +manual steps. Getting updates from others is however a simple and boring task +that *ros-get* can handle. +The command is + + ros-get update + +It updates all packages in the workspace from their repositories. + +**2. which branch?** +**3. are all branches updated?** + + +### *ros-get list* +With all the packages in the workspace, it is useful to get an overview of the +top-level **4. is this true?** packages. The list command provides that functionality. +The command is + + ros-get list + +**5. get other information?? how??** + + +### *ros-get remove* +Removing packages can be done using the + + ros-get remove PKG1 PKG2 ... + +which removes packages PKG1 and PKG2 from the workspace. + +**6. really? what if it is needed by some other package??** +**7. is a package removed automatically by itself when it is not required any more??** +**8. if so, can you avoid that?** + +## Features in tue-env + +- ``tue-checkout BRANCH`` switch repositories to the given branch name +- ``tue-get --release`` build Debian package +- ``tue-get list-installed`` list manually installed packages (ie not automagically added dependencies) +- ``tue-get dep [PKG]`` list dependencies of PKG + Perhaps up to some depth D ? +- ``tue-git-status`` list branch/revision/status of all repos + +- ``tue-make`` / ``tue-make-dev`` / ``tue-make-dev-isolated`` / ``tue-make-system`` + probably provided by catkin already? + +- ``tue-revert`` and ``tue-revert-undo``. + +- ``tue-set-git-remote`` setup an origin for all packages in the workspace. + Adding a new remote (or deleting one) seems more elementary. Would need + adding a new branch labels for the new remote, although making new branch + labels looks more elementary even without additional remotes. + +- Some form of switching main repositories away from github + (``tue-robocup-set-github-origin`` and ``tue-robocup-reset-github-origin``). + +- ``tue-status`` dump catkin system dir, tue-env packages, tue repository status ?? + +- tue-data (no idea wht it is) +- tue-dashboard (no idea what it is) + +### Features that we may not want to support + +- ``tue-create ros-kpg PACKAGE_NAME [DEPENDENCY1 DEPENDENCY2 ..]`` code generator for ROS package boiler-plate +- ``tue-create cpp-class CLASS_NAME PROJECT SUPER_CLASS`` code generator for cpp class. + Code generators could be a separate set of scripts, probably by extracting + from tue-create (or even keeping tue-create). + +- ``tue-env cd`` woud at least be bash. Likely also exists as ``roscd``? +- time-zone commands +- apt-get-proxy +- ``tue-save-map`` + diff --git a/src/ros_get/__main__.py b/src/ros_get/__main__.py index 95756a2..2d0d0df 100644 --- a/src/ros_get/__main__.py +++ b/src/ros_get/__main__.py @@ -9,22 +9,23 @@ def main(): subparsers = parser.add_subparsers() - subparser = subparsers.add_parser('install', help='install packages') + # Package management commaneds. + subparser = subparsers.add_parser('install', help='Install packages.') subparser.set_defaults(func='install') subparser.add_argument('pkgs', nargs='+', metavar='pkg') - subparser = subparsers.add_parser('update', help='update all packages in the workspace to the latest version') + subparser = subparsers.add_parser('update', help='Update all packages in the workspace to the latest version.') subparser.set_defaults(func='update') - subparser = subparsers.add_parser('list', help='list all installed packages') + subparser = subparsers.add_parser('list', help='List all installed packages.') subparser.set_defaults(func='list_installed') - subparser = subparsers.add_parser('remove', help='remove packages') + subparser = subparsers.add_parser('remove', help='Remove packages.') subparser.set_defaults(func='remove') subparser.add_argument('pkgs', nargs='+', metavar='pkg') # workspace commands - subparser = subparsers.add_parser('ws-create', help='create a new workspace') + subparser = subparsers.add_parser('ws-create', help='Create a new workspace.') subparser.set_defaults(func='create') subparser.add_argument('dir') subparser.add_argument( @@ -33,23 +34,23 @@ def main(): help='Explicitly extend the result-space of another catkin workspace, ' 'overriding the value of $CMAKE_PREFIX_PATH.') subparser.add_argument( - '--name', help='give a name to the workspace, if not given, the name ' - 'will be inferred by the directory name') + '--name', help='Give a name to the workspace. If not given, the name ' + 'will be inferred by the directory name.') - subparser = subparsers.add_parser('ws-switch', help='switch to a workspace') + subparser = subparsers.add_parser('ws-switch', help='Switch to a workspace.') subparser.set_defaults(func='switch') subparser.add_argument('name') - subparser = subparsers.add_parser('ws-save', help='Saves the current workspace') + subparser = subparsers.add_parser('ws-save', help='Saves the current workspace.') subparser.set_defaults(func='save') subparser.add_argument('dir') subparser.add_argument( - '--name', help='give a name to the workspace, if not given, the name will be inferred by the directory name') + '--name', help='Give a name to the workspace. If not given, the name will be inferred by the directory name.') - subparser = subparsers.add_parser('ws-list', help='list all saved workspaces') + subparser = subparsers.add_parser('ws-list', help='List all saved workspaces.') subparser.set_defaults(func='list_workspaces') - subparser = subparsers.add_parser('ws-locate', help='prints the path to the current workspace') + subparser = subparsers.add_parser('ws-locate', help='Prints the path to the current workspace.') subparser.set_defaults(func='locate') autocomplete(parser)