Pre- and Post-installation Disk Layout reference
================================================

.. highlight:: catkin-sh

.. rubric:: Source directory

This page describes the intended layout of build and install folders, in particular with respect to the Filesystem Hierarchy standard (FHS).


e.g. for package 'pkg'::

   src/
      pkg/
         CMakeLists.txt
         package.xml  # contains inter-package and system dependencies
                      # as specified in `REP 127 <http://www.ros.org/reps/rep-0127.html>`_

         include/
            pkg/
               header.hpp
               otherheader.hpp
         msg/
            PkgMsg.msg
         src/
            pkg/
               __init__.py
               module.py

               CMakeLists.txt
               source.cpp
         srv/
            PkgSrv.srv

.. todo:: Mention what happens with a ``manifest.xml`` file for backward compatibility with rosbuild

.. rubric:: Build directory

::

   build/
      CATKIN_IGNORE               # an empty file to guide catkin to not search in subfolders for package.xml files
      CMakeCache.txt
      cmake_install.cmake
      Makefile

      devel/                      # the layout of that folder follows the (see install directory)

         .catkin                  # identifies folder as a catkin devel/install space
                                  # it contains a semicolon separated list of source folders if the workspace is a devel space
         env.sh
         setup.bash
         setup.sh
         setup.zsh
         _setup_util.py           # functions for the setup shell scripts

         bin/                     # just "anointed" central binaries (i.e. rosrun)

         etc/                     # environment hooks, configuration files
            catkin/
               profile.d/
                  10.ros.sh       # e.g. defining the ROS_MASTER_URI
            langs/                # to determine which message generators are available
               roscpp             # contains "C++"
               rospy              # contains "Python"

         include/                 # header files of generated code

         lib/                     # all compiled libraries go here
            pkgconfig/            # generated .pc files for all packages
            pythonX.Y/
               dist-packages/
                  pkg/            # generated Python code
                     __init__.py  # generated file to relay imports into src directory of that package
            pkg/                  # compiled binaries of that package

         share/                   # all package-specific but architecture independent files
            pkg/                  # one folder per package
               cmake/             # generated pkgConfig.cmake and pkgConfig-version.cmake for find_package()

      CMakeFiles/


      pkgN/                       # the usual CMake-generated stuff
         catkin_generated/        # files generated by catkin
         cmake/
         CMakeFiles
         cmake_install.cmake
         installspace/            # files generated by catkin which will be installed
         Makefile
         ...


.. rubric:: Install directory

The layout of the install directory follows the `Filesystem Hierarchy Standard (FHS) <http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard>`_.

::

   /opt/ros/groovy/           # defined by the CMAKE_INSTALL_PREFIX
                              # very similar to the devel space folder
                              # therefore in the following only the differences are mentioned

      .catkin                 # identifies folder as a catkin devel/install space
                              # the file is empty which indicates that it is an installspace

      lib/
         pythonX.Y/
            dist-packages/
               pkg/           # besides the generated Python code
                              # contains the Python source code of package

      include/                # besides the generated header files
                              # contains all header files from the source directories

      share/
         pkg/                 # further resources (i.e. icons) copied from source directory
            manifest.xml      # provide export information for legacy rosmake based stacks/packages
            action/
            msg/
               Foo.msg
               Bar.msg
            something.launch  # the rest is as the package installs it

      stacks/
         dry_stack1           # packages built via legacy rosmake
         dry_stack2           # packages built via legacy rosmake