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 &)

PackageMap &	operator= (const PackageMap &)

	PackageMap (PackageMap &&)

PackageMap &	operator= (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 ( )

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

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

◆ PackageMap() [2/3]

PackageMap ( const PackageMap & )

◆ PackageMap() [3/3]

PackageMap ( PackageMap && )

◆ ~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_message When 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= ( const PackageMap & )

◆ operator=() [2/2]

PackageMap& operator= ( 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::exception if 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:

drake/multibody/parsing/package_map.h