<> {{{#!wiki solid/yellow It is recommended to use [[vcstool]] instead of wstool. }}} = wstool = Command-line tools for maintaining a workspace of projects from multiple version-control systems. * Maintainer status: unmaintained * Maintainer: none * License: BSD * Bug / feature tracker: https://github.com/vcstools/wstool/issues * Source: git https://github.com/vcstools/wstool.git (branch: master) wstool provides commands to manage several local SCM repositories (supports git, mercurial, subversion, bazaar) based on a single workspace definition file (.rosinstall). '''wstool replaces the [[rosws]] tool for catkin workspaces'''. As catkin workspaces create their own setup file and environment, wstool is reduced to version control functions only. So wstool does not have a "regenerate" command, and does not allow adding non-version controlled elements to workspaces. In all other respects, it behaves the same as rosws. wstool is not a rewrite. It is intended to reuse most of the rosws tool code and thus also produce .rosinstall files that are compatible with those used by rosws. wstool depends on the [[vcstools]] package, and for a transitional period it will also depend on the [[rosinstall]] package (later that dependency will be inverted). == Installation == To install, use {{{ $ sudo apt-get install python-wstool }}} or when that is not possible, fall back to pip: {{{ $ sudo pip install -U wstool }}} == Changes from rosws and rosbuild == * rosbuild and rosws used the ROS_WORKSPACE environment variable to determine what workspace you are working in. catkin determines this from the current working directory. wstool's workspace is specified with the -t parameter * The root of the wstool workspace is the root of the catkin source directory: {{{ ~/ros_catkin_ws/ <-- Invoke catkin_make from here ├── src/ <-- Use this path for wstool -t │   ├── repository1/ │ │ ├── .git/ │   │ └── my_files │ ├── repository2/ │ │ ├── .git/ │ │ └── my_other_files │ └── .rosinstall ├── devel/ └── build/ }}} * rosws generated setup.*sh files when called with commands "init" or "regenerate", and a CMakeLists.txt instead when also passed the option "--catkin". Both had implicit dependencies to the ROS ecosystem. wstool avoids those dependencies and leaves it to the user or other tools (e.g. catkin) to create such environment setup files. * Similarly, workspace overlaying is managed by catkin rather than wstool. This means you shouldn't put your workspace underlay in your rosinstall file or use the underlay to initialize your workspace. == Using wstool == === Create a catkin Workspace with wstool === First, create a catkin workspace: {{{ $ mkdir ~/ros_catkin_ws $ cd ~/ros_catkin_ws }}} === Initialize the Workspace Without a rosinstall file === This will initialize an empty workspace. If you have a rosinstall file that you want to base your workspace on, skip to Initialize the Workspace from a rosinstall File below. {{{ $ wstool init src }}} If you have rosinstall files to add to the workspace, proceed to Merge in Additional rosinstall Files below. === Initialize the Workspace from a rosinstall File === If you have already initialized your workspace, skip this step. If you have rosinstall files to add to the workspace, proceed to Merge in Additional rosinstall Files below. {{{ $ wstool init src PATH_TO_ROSINSTALL_FILE.rosinstall }}} If you have rosinstall files to add to the workspace, proceed to Merge in Additional rosinstall Files below. === Merge in Additional rosinstall Files === For each rosinstall file you want to add to your workspace, run this command {{{ $ wstool merge -t src PATH_TO_ROSINSTALL_FILE.rosinstall }}} === Updating the Workspace === After you've created your workspace and added repositories, you should update it to download the latest versions. {{{ wstool update -t src }}} == Further Documentation == Since the syntax and semantics are the same as for rosws, for the time being use the rosws syntax docs at: http://www.ros.org/doc/independent/api/rosinstall/html/