<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>librospack: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">librospack
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">librospack Documentation</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="overview"></a>
Overview</h1>
<p><b>librospack</b> is the ROS stackage (stack/package) management library.</p>
<p>librospack is part dpkg, part pkg-config. The main function of librospack is to crawl through the stackages in ROS_ROOT and ROS_PACKAGE_PATH, read and parse the <b>manifest</b> for each stackage, and assemble a complete dependency tree for all stackages.</p>
<p>Using this tree, librospack can answer a number of queries about stackages and their dependencies. Common queries include:</p>
<ul>
<li>find : return the absolute path to a stackage</li>
<li>depends : return a list of all of a stackage's dependencies</li>
<li>depends-on : return a list of stackages that depend on the given stackage</li>
<li>export : return flags necessary for building and linking against a package</li>
</ul>
<p>librospack is intended to be cross-platform.</p>
<h2><a class="anchor" id="crawling"></a>
Crawling algorithm</h2>
<p>librospack crawls in the following order: the directory ROS_ROOT, followed by the colon-separated list of directories ROS_PACKAGE_PATH, in the order they are listed.</p>
<p>During the crawl, librospack examines the contents of each directory, looking for a file called <b>manifest.xml</b> (for packages) or <b>stack.xml</b> (for stacks). If such a file is found, the directory containing it is considered to be a ROS stackage, with the stackage name equal to the directory name. The crawl does not descend further once a manifest is found (i.e., stackages cannot be nested inside one another).</p>
<p>If a manifest is not found in a given directory, each subdirectory is searched. This subdirectory search is prevented if a file called <b>rospack_nosubdirs</b> is found. The directory itself is still searched for a manifest, but its subdirectories are not crawled.</p>
<p>If multiple stackages by the same name exist within the search path, the first one found wins. It is strongly recommended that you keep stackages by the same name in separate trees, each having its own element within ROS_PACKAGE_PATH. That way, you can deterministically control the search order by the way that you specify ROS_PACKAGE_PATH. The search order within a given element of ROS_PACKAGE_PATH can be unpredictably affected by the details of how files are laid out on disk.</p>
<h2><a class="anchor" id="efficiency"></a>
Efficiency considerations</h2>
<p>librospack re-parses the manifest files and rebuilds the dependency tree on each execution. However, it maintains a cache of stackage directories in ROS_HOME/rospack_cache (or ROS_HOME/rosstack_cache). This cache is updated whenever there is a cache miss, or when the cache is 60 seconds old. You can change this timeout by setting the environment variable ROS_CACHE_TIMEOUT, in seconds. Set it to 0.0 to force a cache rebuild on every invocation of librospack.</p>
<p>librospack's performance can be adversely affected by the presence of very broad and/or deep directory structures that don't contain manifest files. If such directories are in librospack's search path, it can spend a lot of time crawling them only to discover that there are no stackages to be found. You can prevent this latency by creating a <b>rospack_nosubdirs</b> file in such directories. If librospack seems to be running annoyingly slowly, you can call profile(), which will print out the slowest trees to crawl.</p>
<h2><a class="anchor" id="dependencies"></a>
Minimal dependencies</h2>
<p>Because librospack is the tool that determines dependencies, it must have minimal dependencies. librospack contains a copy of the TinyXML library, and depends on Boost. If gtest is available, then tests can be run.</p>
<h1><a class="anchor" id="codeapi"></a>
Code API</h1>
<p>librospack is used primarily in command-line tools (rospack and rosstack), but can be used in other contexts. See the API documentation for Rospack and Rosstack. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sun Aug 25 2013 13:51:52 for librospack by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.3.1
</small></address>
</body>
</html>
