Directory Structure and Style

Abstract

This document is intended to set down the preferred directory structure for the NRMC team.

Why?

Having a clean, uniform directory structure is important for a number of reasons. It allows collaborators on the team to be able to quickly figure out what you are doing, what files go where and what files do which thing. As such, your directory structure must adhere to the rules set down below before it can be merged into master. Since refactoring directory structures and the cmake build system that lives within it is tedious, error prone and, in general, annoying, it is best if the style guide is followed from the beginning.

What different types of things are covered by this structure guide?

There a few main components of our software system that are covered by this structure guide:

• Headers (C++)

• Source Files (C++)

• actionlib Files (ROS)

• Python Source (referred to as scripts)

• msg Files (ROS)

• srv Files (ROS)

• launch files (ROS)

There a few different types of source files, and they have their own special place in the directory structure

• Libraries

• Executables

• Tests

There are even a few different types of Tests

• Integration Tests : Makes sure that the code works with the outside world

• Unit Tests : Makes sure that the code passes interface assumptions

Example Directory Structure

So, with the definitions out of the way, let’s look at the directory structure of the vesc_access library as an example

NRMC2018
  |--src
     |--controls
        |--wheel_control
           CMakeLists.txt
           |--include
              |--vesc_access
                 vesc_access.h
           |--src
              |--vesc_accces
                 vesc_acess.cpp
                 |--test
                    vesc_access_tests.cpp
              ros_executable.cpp
           package.xml
           |--test
              vesc_access_integration_test.cpp
           |--action
              wheel_action.action
           |--msg
              custom_msg.msg
           |--srv
              custom_src.srv
           |--scripts
              my_python_script.py
           |--launch
              launch_my_package.launch
              vesc_access_integration_test.launch

Analyzing the package structure

Lets take a second to analyze the package structure above and figure out what it’s all about. The main pieces of beef are in the include and src folders. If you are making a cpp library, in the src directory, there should be a folder in which the library lives. The file should be named the name of the library in under_score font as per ROS style guide standards. The same is true for the include directory. The next file is a text file called requirements.txt that contains a list of requirements that describe the interface of the library. Underneath that folder should be a folder called tests. This folder contains a cpp file that uses GMock and GTest to test your code and its expectations. These are the unit tests for the code. If your code needs integration tests, you’ll need to compile an executable from a cpp file. This file should be placed in a file called test, which is on the same level as the package’s CMakeLists.txt with the name executable_name_integration_tests.cpp. When you have an integration test, you will need a roslaunch file to launch it. This can be accomplished by placing a file in the launch directory with the same name as your cpp file that defines the executable to be launched.

If there is a Cpp ROS executable in the directory, that should go on the top level of src.

If you have any python scripts, those go in the scripts folder. Any launch files go in the launch folder, custom messages go in msg, services in srv, action files go in the action folder.

If you have any questions or find anything in this wiki entry to be ambiguous, please let me know.

Marc