• Diff for "Stacks"
Differences between revisions 28 and 34 (spanning 6 versions)
⇤ ← Revision 28 as of 2009-12-30 08:15:25 →
Size: 4472
Editor: KenConley
Comment:
← Revision 34 as of 2013-10-18 23:01:47 → ⇥
Size: 27
Editor: WilliamWoodall
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
<<MenuNavi(Menus/ROSFilesystemConcepts)>>
<<TOC(3)>>

[[Packages]] in ROS are organized into ROS ''stacks''. Whereas the goal of packages is to create minimal collections of code for easy ''reuse'', the goal of stacks is to simplify the process of code ''sharing''. Stacks are the primary mechanism in ROS for distributing software. Each stack has an associated version and can declare dependencies on other stacks. These dependencies also declare a version number, which provides greater stability in development.

Stacks collect packages that collectively provide functionality, such as a navigation stack or a manipulation stack. Unlike a traditional software library that you link against at compile time, these stacks can also provide this functionality at runtime via ROS [[Topics|topics]] and [[Services|services]].

Stacks are easy to create by hand. A stack is simply a directory descended from `ROS_ROOT` or `ROS_PACKAGE_PATH` (see [[ROS/EnvironmentVariables|ROS Environment Variables]]) that has a [[Stack Manifest|stack.xml]] file in it. Any Packages in this directory are considered to be part of the Stack.

For release purposes, a `CMakeLists.txt` and `Makefile` should also be put into the root of the stack. The [[roscreate|roscreate-stack]] tool can generate this file automatically.

Please see the [[Stack Manifest]] section for documentation on how to write `stack.xml` files.

== Command-line Tools ==

[[rosstack]] is the primary ROS tool for interacting with ROS stacks. It is the stack-level analogue of the [[rospack]] tool for [[Packages|packages]].

<<MenuNavi(Menus/ROSFilesystemConcepts)>>

<<TOC(3)>>

Software in ROS is organized in ''packages''. A package might contain ROS [[Nodes|nodes]], a ROS-independent library, a dataset, configuration files, a third-party piece of software, or anything else that logically constitutes a useful module. The goal of these packages it to provide this useful functionality in an easy-to-consume manner so that software can be easily reused. In general, ROS packages follow a "Goldilocks" principal: enough functionality to be useful, but not too much that the package is heavyweight and difficult to use from other software.

Packages are easy to create by hand or with tools like [[roscreate|roscreate-pkg]]. A ROS package is simply a directory descended from `ROS_ROOT` or `ROS_PACKAGE_PATH` (see [[ROS/EnvironmentVariables|ROS Environment Variables]]) that has a [[Manifest|manifest.xml]] file in it. Packages may be organized together into ROS [[Stacks|stacks]].

Please see the [[Manifest]] section for documentation on how to read and write `manifest.xml` files.

== Common Files and Directories ==

ROS packages tend to follow a common structure. Here are some of the directories and files you may notice.

 * `bin/`: compiled binaries
 * `include/package_name`: C++ include headers (make sure to export in the [[Manifest]])
 * `msg/`: [[msg|Message (msg) types]]
 * `src/package_name/`: Source files, especially Python source that are exported to other packages.
 * `srv/`: [[srv|Service (srv) types]]
 * `scripts/`: executable scripts
 * `CMakeLists.txt`: CMake build file (see [[CMakeLists]])
 * `manifest.xml`: Package [[Manifest]]
 * `mainpage.dox`: many packages will often place their [[Doxygen]] mainpage documentation here

== Command-line Tools ==

Packages are a very central concept to how files in ROS are organized, so there are quite a few tools in ROS that help you manage them. This includes:

 * [[rospack]]: find and retrieve information about packages. The [[ROS/BuildSystem|build system]] also uses [[rospack]] to locate a package and build its dependencies.
 * [[roscreate|roscreate-pkg]]: create a new package.
 * [[rosmake]]: build a package and its dependencies.
 * [[rosdep]]: install system dependencies of a package.
 * [[rxdeps]]: visualizes package dependencies as a graph.

There are also extensions to common Unix shells that provide additional functionality to help you navigate and use packages. The most commonly used of these is [[rosbash]], which provides ROS-variants of common Unix shell commands. The most commonly used of these is `roscd`, which performs a `cd` to the directory of a package, e.g.

{{{
roscd roscpp_tutorials
}}}

== Client Library Support ==

=== Python ===

In Python, you can use the `roslib.stacks` module in the [[roslib]] package to get information about ROS stacks.		 #redirect rosbuild/Stacks

Wiki: Stacks (last edited 2013-10-18 23:01:47 by WilliamWoodall)

Except where otherwise noted, the ROS wiki is licensed under the
Creative Commons Attribution 3.0