Drake
Drake C++ Documentation
PackageMap Class Referencefinal

Detailed Description

Maps ROS package names to their full path on the local file system.

It is used by the SDF and URDF parsers when parsing files that reference ROS packages for resources like mesh files. This class can also download remote packages from the internet on an as-needed basis via AddRemote().

#include <drake/multibody/parsing/package_map.h>

Classes

struct  RemoteParams
 Parameters used for AddRemote(). More...
 

Public Member Functions

 PackageMap ()
 A constructor that initializes a default map containing only the top-level drake manifest. More...
 
 ~PackageMap ()
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 PackageMap (const PackageMap &)
 
PackageMapoperator= (const PackageMap &)
 
 PackageMap (PackageMap &&)
 
PackageMapoperator= (PackageMap &&)
 
Functions for looking up packages in the map
int size () const
 Returns the number of entries in this PackageMap. More...
 
std::vector< std::string > GetPackageNames () const
 Returns the package names in this PackageMap. More...
 
bool Contains (const std::string &package_name) const
 Returns true if and only if this PackageMap contains package_name. More...
 
const std::string & GetPath (const std::string &package_name, std::optional< std::string > *deprecated_message=nullptr) const
 Obtains the path associated with package package_name. More...
 
std::string ResolveUrl (const std::string &url) const
 Returns a resolved path for url. More...
 
Functions for adding packages to the map
void Add (const std::string &package_name, const std::string &package_path)
 Adds package package_name and its path, package_path. More...
 
void AddMap (const PackageMap &other_map)
 Adds all packages from other_map into this. More...
 
void AddPackageXml (const std::string &filename)
 Adds an entry into this PackageMap for the given package.xml filename. More...
 
void AddRemote (std::string package_name, RemoteParams params)
 Adds an entry into this PackageMap for the given package_name, which will be downloaded from the internet (with local caching). More...
 
void PopulateFromFolder (const std::string &path)
 Crawls down the directory tree starting at path searching for directories containing the file package.xml. More...
 
void PopulateFromEnvironment (const std::string &environment_variable)
 Obtains one or more paths from environment variable environment_variable. More...
 
void PopulateFromRosPackagePath ()
 Obtains one or more paths from the ROS_PACKAGE_PATH environment variable. More...
 
Functions for modifying packages already in the map
std::optional< std::string > GetDeprecated (const std::string &package_name) const
 Returns the deprecation message for package package_name if it has been set as deprecated. More...
 
void SetDeprecated (const std::string &package_name, std::optional< std::string > deprecated_message)
 Sets or clears the deprecation message for package package_name. More...
 
void Remove (const std::string &package_name)
 Removes package package_name and its previously added path. More...
 

Static Public Member Functions

static class PackageMap MakeEmpty ()
 A factory method that initializes an empty map. More...
 

Friends

std::ostream & operator<< (std::ostream &out, const PackageMap &package_map)
 

Constructor & Destructor Documentation

◆ PackageMap() [1/3]

PackageMap ( const PackageMap )

◆ PackageMap() [2/3]

◆ PackageMap() [3/3]

A constructor that initializes a default map containing only the top-level drake manifest.

See PackageMap::MakeEmpty() to create an empty map.

◆ ~PackageMap()

~PackageMap ( )

Member Function Documentation

◆ Add()

void Add ( const std::string &  package_name,
const std::string &  package_path 
)

Adds package package_name and its path, package_path.

Throws if package_name is already present in this PackageMap with a different path, or if package_path does not exist.

◆ AddMap()

void AddMap ( const PackageMap other_map)

Adds all packages from other_map into this.

Throws if other contains a package with the same package_name as one already in this map but with incompatible details (e.g., a different local path).

◆ AddPackageXml()

void AddPackageXml ( const std::string &  filename)

Adds an entry into this PackageMap for the given package.xml filename.

Throws if filename does not exist or its embedded name already exists in this map.

◆ AddRemote()

void AddRemote ( std::string  package_name,
RemoteParams  params 
)

Adds an entry into this PackageMap for the given package_name, which will be downloaded from the internet (with local caching).

The data will not be downloaded until necessary, i.e., when GetPath() is first called for the package_name. Throws if the package_name or params are invalid. Downloading requires a valid /usr/bin/python3 interpreter, which will be invoked as a subprocess.

See DRAKE_ALLOW_NETWORK for an environment variable option to disable network fetching. AddRemote may still be used even with network fetching disabled – in that case, the urls must contain a "file://" URL or the download cache must already contain a previously-downloaded copy of the package (with the same sha256 checksum).

◆ Contains()

bool Contains ( const std::string &  package_name) const

Returns true if and only if this PackageMap contains package_name.

◆ GetDeprecated()

std::optional<std::string> GetDeprecated ( const std::string &  package_name) const

Returns the deprecation message for package package_name if it has been set as deprecated.

A value of std::nullopt implies no deprecation. Aborts if no package named package_name exists in this PackageMap.

◆ GetPackageNames()

std::vector<std::string> GetPackageNames ( ) const

Returns the package names in this PackageMap.

The order of package names returned is unspecified.

◆ GetPath()

const std::string& GetPath ( const std::string &  package_name,
std::optional< std::string > *  deprecated_message = nullptr 
) const

Obtains the path associated with package package_name.

Aborts if no package named package_name exists in this PackageMap.

Parameters
[out]deprecated_messageWhen passed as nullptr (its default value), then in case the package_name is deprecated a deprecation message will be logged. When passed as non-nullptr the deprecation message will be output into this argument and will not be logged; if the package_name is not deprecated, the message will be set to nullopt.

◆ MakeEmpty()

static class PackageMap MakeEmpty ( )
static

A factory method that initializes an empty map.

◆ operator=() [1/2]

PackageMap& operator= ( PackageMap &&  )

◆ operator=() [2/2]

PackageMap& operator= ( const PackageMap )

◆ PopulateFromEnvironment()

void PopulateFromEnvironment ( const std::string &  environment_variable)

Obtains one or more paths from environment variable environment_variable.

Crawls downward through the directory tree(s) starting from the path(s) searching for package.xml files. For each of these files, this method adds a new entry into this PackageMap where the key is the package name as specified within package.xml and the value is the path to the package.xml file. Multiple paths can be specified by separating them using the ':' symbol. For example, the environment variable can contain [path 1]:[path 2]:[path 3] to search three different paths.

If a package already known by the PackageMap is found again with a conflicting path, a warning is logged and the original path is kept.

If a path does not exist or is unreadable, a warning is logged.

Warning
This function must not be used when populating manifests from the ROS_PACKAGE_PATH environment variable. It will throw an exception when that is attempted. Instead, use PopulateFromRosPackagePath().

◆ PopulateFromFolder()

void PopulateFromFolder ( const std::string &  path)

Crawls down the directory tree starting at path searching for directories containing the file package.xml.

For each of these directories, this method adds a new entry into this PackageMap where the key is the package name as specified within package.xml and the directory's path is the value. If a package already known by the PackageMap is found again with a conflicting path, a warning is logged and the original path is kept. If the path does not exist or is unreadable, a warning is logged.

◆ PopulateFromRosPackagePath()

void PopulateFromRosPackagePath ( )

Obtains one or more paths from the ROS_PACKAGE_PATH environment variable.

Semantics are similar to PopulateFromEnvironment(), except that ROS-style crawl termination semantics are enabled, which means that subdirectories of already-identified packages are not searched, and neither are directories which contain any of the following marker files:

  • AMENT_IGNORE
  • CATKIN_IGNORE
  • COLCON_IGNORE

◆ Remove()

void Remove ( const std::string &  package_name)

Removes package package_name and its previously added path.

Throws if package_name is not present in this PackageMap.

◆ ResolveUrl()

std::string ResolveUrl ( const std::string &  url) const

Returns a resolved path for url.

URL schemes are either file:// for local files or package:// (or model://).

Exceptions
std::exceptionif the url cannot be resolved.

◆ SetDeprecated()

void SetDeprecated ( const std::string &  package_name,
std::optional< std::string >  deprecated_message 
)

Sets or clears the deprecation message for package package_name.

A deprecated_message value of std::nullopt implies no deprecation. Aborts if no package named package_name exists in this PackageMap.

◆ size()

int size ( ) const

Returns the number of entries in this PackageMap.

Friends And Related Function Documentation

◆ operator<<

std::ostream& operator<< ( std::ostream &  out,
const PackageMap package_map 
)
friend

The documentation for this class was generated from the following file: