Previous: Toolboxes and Domains	Next: Concepts

Packages are collections of components (e.g. plugins, units, views, data files, etc.). Each package contains meta information describing its content, dependencies to include paths, library paths and libraries as well as its dependencies to other packages.

This mechanism ensures, that components depending on packages will inherit their include paths, libraries etc. that are necessary for the build process.

The meta information is stored in a so called "*.package" file, that must reside within the top directory of the package.

Package files are used to install and manage packages on your MIRA installation using mirapackage.

Example

MIRA_VERSION(1 2 3)
MIRA_DESCRIPTION("A detailed description of the package and its content")
MIRA_TAGS("robot;localization;mapping;slam")
MIRA_AUTHOR("Peter Griffin; Marge Simpson")
MIRA_DEVELOPMENT_STATE(STABLE)
MIRA_REQUIRE_PACKAGE(MIRAFramework)
MIRA_REQUIRE_PACKAGE(Mapping 2.0.1)
MIRA_OPTIONAL_PACKAGE(Python)
MIRA_RUNTIME_PACKAGE(JavaScript)
# our own include dir
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_LIST_DIR}/include)
# external include dirs
INCLUDE_DIRECTORIES(${OPENCV_INCLUDE_DIRS})
LINK_DIRECTORIES(${OPENCV_LIBRARY_DIRS}
MIRA_LINK_LIBRARIES(
    ${BOOST_SYSTEM_LIBRARY}
    ${OPENCV_CORE_LIBRARY}
)
MIRA_CHANGELOG(
"
Version 1.2.3
-----------------------------------------
- updates and fixes
- ...
Version 1.2.1 (Release date: 2012-01-01)
-----------------------------------------
- update and bugfixes
- ...
Version 1.0.0 (Release date: 2011-01-01)
----------------------------------------
- initial version
")

Description

In the following the above example is examined line by line:

MIRA_VERSION(1 2 3)

MIRA_VERSION(major minor patch)

Set the version information of the current package and its contained libraries. It uses the common version scheme consisting of major version, minor version and patch number.

MIRA_DESCRIPTION("A detailed description of the package and its content")

Sets the detailed description of the current package.

MIRA_TAGS("robot;localization;mapping;slam")

Sets some tags for the current package, that are used by install tools to group the packages into categories.

MIRA_AUTHOR("Peter Griffin; Marge Simpson")

Set the author information for the current package.

MIRA_DEVELOPMENT_STATE(STABLE)

MIRA_DEVELOPMENT_STATE(EXPERIMENTAL | STABLE | RELEASE | DEPRECATED)

Set the development state of the package. It can be one of the three states:

"EXPERIMENTAL": The package is not stable and under development (use a stable version of it).
"STABLE": It may be still under development, but this package is working.
"RELEASE": This package is guaranteed to be reviewed (running a complete review process) and provides test cases to ensure it is stable and working.

MIRA_REQUIRE_PACKAGE(MIRAFramework)
MIRA_REQUIRE_PACKAGE(Mapping 2.0.1)
MIRA_OPTIONAL_PACKAGE(Python) 
MIRA_RUNTIME_PACKAGE(JavaScript)

The MIRA_REQUIRE_PACKAGE macro specifies a necessary dependency to another package. This package is required to build or use the current package. The dependencies of the specified package will be included transitively. As an optional second argument, the minimum required version can be passed to the macro MIRA_REQUIRE_PACKAGE. Additionally, all include paths, libraries, etc. of the required package are imported.

In contrast MIRA_OPTIONAL_PACKAGE imports the specified dependency only, if such a package exists.

MIRA_RUNTIME_PACKAGE does not import any dependency (our package will compile fine without it) but marks the other package as needed at runtime. (e.g. Channel or RPC dependency)

# our own include dir
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_LIST_DIR}/include)
# external include dirs
INCLUDE_DIRECTORIES(${OPENCV_INCLUDE_DIRS})

Specifies the include directories that are necessary for the build process, when the package is used.

Usually, a package should always specify the directories to its own headers. Those directories must be specified relatively to ${CMAKE_CURRENT_LIST_DIR} as shown above in the first line.

LINK_DIRECTORIES(${OPENCV_LIBRARY_DIRS}

Specifies the link directories that are necessary for the build process, when the package is used (see above).

MIRA_LINK_LIBRARIES(
    ${BOOST_SYSTEM_LIBRARY}
    ${OPENCV_CORE_LIBRARY}
)

Specifies the libraries that are required by the package. This ensures, that other libraries, that depend on the package will also link to these specified libraries (transitive library dependency).

Furthermore, the macro MIRA_CHANGELOG can be used to document the changes from one version to another. The whole changelog is a single string. The format and content can be chosen by the user. It is also possible to insert HTML tags, which will be used in mirapackage for displaying the changelog.

External packages

Packages can also be used to describe and install external code components or libraries. TODO...

MIRA_MARK_AS_EXTERNAL_PACKAGE() This macro will mark the current package as a none-MIRA package. This is necessary for useful/necessary for external libraries, which are handled as packages during building (e.g. Ogre).

Next: Concepts