catkin workspace creation in ROS - Deep Dive

Overview - catkin workspace creation

What is it?

A catkin workspace is a special folder structure used in ROS (Robot Operating System) to organize and build robot software packages. It helps you keep your code, dependencies, and build files neatly arranged so ROS can compile and run your robot programs. Creating a catkin workspace means setting up this folder structure and initializing it so you can start adding your robot code.

Why it matters

Without a catkin workspace, managing robot software becomes chaotic and error-prone. You would struggle to build multiple packages together or share code between projects. The catkin workspace solves this by providing a standard way to organize and build your robot code, making development faster, more reliable, and easier to share with others.

Where it fits

Before creating a catkin workspace, you should understand basic command-line navigation and have ROS installed. After learning workspace creation, you will move on to creating and building ROS packages, writing robot nodes, and managing dependencies.

Mental Model

Core Idea

A catkin workspace is like a dedicated workshop where all your robot parts (code packages) are stored, built, and prepared to work together smoothly.

Think of it like...

Imagine you are building a model airplane. The catkin workspace is your workbench where you keep all the parts, tools, and instructions organized so you can assemble the plane without losing pieces or mixing things up.

catkin_ws/          ← Your workspace folder
├── src/             ← Source folder where packages live
│   ├── package1/    ← Your robot code packages
│   └── package2/
├── build/           ← Temporary build files (created after build)
├── devel/           ← Development environment files (created after build)
└── install/         ← Installed files (optional, after install)

Build-Up - 7 Steps

1

Foundation

Understanding ROS and Packages

Concept: Learn what ROS is and what packages are in ROS.

ROS is a system to help robots talk to each other and run programs. Packages are like folders that hold robot programs and files. Each package does one job, like controlling a motor or reading a sensor.

Result

You know that ROS uses packages to organize robot code.

Understanding packages is key because the workspace is built to hold and manage these packages efficiently.

2

Foundation

What is a Catkin Workspace?

Concept: Introduce the catkin workspace as the place to build and organize ROS packages.

A catkin workspace is a folder with a special structure that ROS uses to find, build, and run your packages. It has a 'src' folder where you put your packages, and other folders created when you build your code.

Result

You see the folder structure needed to start working with ROS packages.

Knowing the workspace structure helps you keep your robot projects organized and ready to build.

3

Intermediate

Creating the Workspace Folder

Concept: Learn the commands to create the workspace folder and initialize it.

Use terminal commands: 1. mkdir -p ~/catkin_ws/src # Make workspace and source folders 2. cd ~/catkin_ws/ # Go to workspace folder 3. catkin_make # Initialize and build workspace This sets up the workspace and prepares it for packages.

Result

A new catkin workspace folder with 'src' created and ready to build.

Creating the workspace folder with the right structure is the first step to managing your robot code effectively.

4

Intermediate

Building the Workspace with catkin_make

🤔Before reading on: Do you think 'catkin_make' only compiles code or also sets up environment files? Commit to your answer.

Concept: Understand what happens when you run 'catkin_make' in the workspace.

'catkin_make' compiles all packages inside 'src' and creates 'build' and 'devel' folders. The 'devel/setup.bash' file sets environment variables so ROS knows where to find your packages.

Result

Workspace is built, and environment files are created for ROS to use your packages.

Knowing that 'catkin_make' does both build and environment setup helps you prepare your system to run your robot code.

5

Intermediate

Sourcing the Workspace Environment

🤔Before reading on: Do you think sourcing 'devel/setup.bash' is permanent or temporary? Commit to your answer.

Concept: Learn how to tell your terminal to use the workspace environment.

Run 'source ~/catkin_ws/devel/setup.bash' in your terminal. This command updates your terminal session so ROS commands know about your workspace packages. You can add this line to your '.bashrc' file to make it automatic.

Result

Your terminal recognizes your workspace packages and can run ROS commands using them.

Sourcing connects your workspace to your terminal session, enabling smooth development and testing.

6

Advanced

Managing Multiple Workspaces

🤔Before reading on: Can you source two workspaces at once without conflicts? Commit to your answer.

Concept: Learn how to overlay multiple catkin workspaces to combine packages.

You can source one workspace after another to overlay them. For example: source ~/catkin_ws/devel/setup.bash source ~/other_ws/devel/setup.bash This lets ROS find packages from both workspaces, useful for combining your code with others'.

Result

Multiple workspaces work together, allowing shared and custom packages to coexist.

Understanding workspace overlays helps manage complex projects with shared and personal code.

7

Expert

Inside catkin_make and Workspace Internals

🤔Before reading on: Do you think 'catkin_make' is a ROS-specific build tool or a wrapper around standard tools? Commit to your answer.

Concept: Explore how 'catkin_make' works under the hood to build your workspace.

'catkin_make' is a convenience tool that wraps CMake and Make. It reads package.xml and CMakeLists.txt files in each package to understand dependencies and build order. It creates 'build' and 'devel' folders to separate build files from source and runtime files. This separation keeps your workspace clean and manageable.

Result

You understand the build process and how ROS manages package dependencies and environment setup.

Knowing the internals of 'catkin_make' helps debug build issues and optimize workspace setup.

Under the Hood

When you run 'catkin_make', it calls CMake to configure the build system based on package metadata. CMake generates Makefiles that know how to compile each package in the right order, respecting dependencies. The build artifacts go into the 'build' folder, while the 'devel' folder holds environment scripts and runtime files. Sourcing 'devel/setup.bash' sets environment variables like ROS_PACKAGE_PATH so ROS tools find your packages.

Why designed this way?

ROS uses catkin and CMake because they are flexible and widely supported tools for building C++ and Python code. Separating source, build, and development files avoids clutter and makes it easy to clean or rebuild parts. The environment setup allows multiple workspaces to coexist without conflicts, supporting modular robot software development.

catkin_make command
   │
   ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  src folder │─────▶│  CMakeLists │─────▶│  build folder│
│ (packages)  │      │  & package.xml│    │ (compiled)  │
└─────────────┘      └─────────────┘      └─────────────┘
                                         │
                                         ▼
                                  ┌─────────────┐
                                  │  devel folder│
                                  │ (env scripts)│
                                  └─────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does running 'catkin_make' automatically make your packages available to ROS commands? Commit yes or no.

Common Belief: Running 'catkin_make' alone is enough for ROS to find and use your packages.

Reality: You must also source the 'devel/setup.bash' file after building to update your environment for ROS to find your packages.

Why it matters: Without sourcing, ROS commands won't recognize your new packages, causing confusion and errors.

Quick: Can you create a catkin workspace anywhere on your computer? Commit yes or no.

Common Belief: You can create a catkin workspace in any folder without restrictions.

Reality: While you can create it anywhere, it's best practice to keep it in your home directory or a dedicated development folder to avoid permission issues and confusion.

Why it matters: Creating workspaces in system folders can cause permission errors and make managing your code harder.

Quick: Does 'catkin_make' build packages in alphabetical order? Commit yes or no.

Common Belief: 'catkin_make' builds packages alphabetically regardless of dependencies.

Reality: 'catkin_make' builds packages in dependency order, ensuring packages are built only after their dependencies.

Why it matters: Building in the wrong order causes build failures and runtime errors.

Quick: If you source multiple workspaces, do their packages merge seamlessly without conflicts? Commit yes or no.

Common Belief: Sourcing multiple workspaces always merges packages without any issues.

Reality: If packages have the same name or conflicting versions, sourcing multiple workspaces can cause conflicts and unexpected behavior.

Why it matters: Ignoring conflicts can lead to hard-to-debug errors and unstable robot software.

Expert Zone

1

The 'devel' folder contains symbolic links and environment scripts that make your workspace behave like an installed ROS environment without copying files.

2

catkin workspaces can be nested or overlaid, but the order of sourcing affects which package versions ROS uses.

3

Using 'catkin_make_isolated' instead of 'catkin_make' builds each package separately, which helps isolate build errors but takes longer.

When NOT to use

Catkin workspaces are not ideal for very large projects or when using ROS 2, which uses colcon as the build tool. For ROS 2, use colcon workspaces instead. Also, if your project is pure Python without ROS dependencies, simpler virtual environments may be better.

Production Patterns

In real projects, developers create multiple catkin workspaces for different robot components and overlay them to combine functionality. Continuous integration systems automate 'catkin_make' builds and environment sourcing to test code before deployment.

Connections

Makefile Build Systems

catkin_make is a wrapper around Makefiles generated by CMake.

Understanding Makefiles helps grasp how catkin_make compiles code and manages dependencies.

Virtual Environments in Python

Both isolate development environments to avoid conflicts between projects.

Knowing virtual environments clarifies why sourcing 'devel/setup.bash' is necessary to activate the workspace environment.

Modular Construction in Manufacturing

Building robot software in packages within a workspace is like assembling a product from modular parts on a factory floor.

Seeing software as modular parts helps understand why workspace organization and build order matter.

Common Pitfalls

#1 Not sourcing the workspace environment after building.

Wrong approach:

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin_make
rosrun my_package my_node

Correct approach:

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin_make
source devel/setup.bash
rosrun my_package my_node

Root cause:

Forgetting that ROS needs environment variables set by sourcing to find your packages.

#2 Creating packages outside the 'src' folder.

Wrong approach:

mkdir -p ~/catkin_ws/my_package
# put code here
catkin_make

Correct approach:

mkdir -p ~/catkin_ws/src/my_package
# put code here
catkin_make

Root cause:

Not understanding that catkin only builds packages inside the 'src' folder.

#3 Running 'catkin_make' inside the 'src' folder instead of workspace root.

Wrong approach:

cd ~/catkin_ws/src
catkin_make

Correct approach:

cd ~/catkin_ws
catkin_make

Root cause:

Misunderstanding that 'catkin_make' must be run from the workspace root to build all packages.

Key Takeaways

A catkin workspace is a structured folder that organizes and builds ROS packages together.

Creating the workspace involves making a 'src' folder and running 'catkin_make' to build and set up environment files.

You must source the workspace's 'devel/setup.bash' file to let ROS find your packages in the current terminal session.

Catkin workspaces manage dependencies and build order automatically, preventing build errors.

Advanced use includes overlaying multiple workspaces and understanding the build internals for debugging.

Practice

1. What is the purpose of creating a catkin workspace in ROS?

easy

A. To organize and build your ROS packages in one place

B. To install ROS system-wide dependencies

C. To run ROS nodes without any packages

D. To update the ROS core automatically

Solution

1. Step 1: Understand what a catkin workspace is

   A catkin workspace is a folder where you keep your ROS packages organized and build them together.

2. Step 2: Identify the purpose of the workspace

   It helps you manage your own ROS projects, not system-wide installations or running nodes without packages.

3. Final Answer:

   To organize and build your ROS packages in one place -> Option A

4. Quick Check:

   Workspace = Organize & build packages [OK]

Hint: Workspace holds your ROS projects and builds them [OK]

Common Mistakes:

• Confusing workspace with system installation
• Thinking workspace runs nodes alone
• Assuming workspace updates ROS core

2. Which command correctly creates the source folder inside a catkin workspace named catkin_ws in your home directory?

easy

A. catkin_make ~/catkin_ws/src

B. mkdir ~/catkin_ws/src

C. mkdir -p ~/catkin_ws/src

D. source ~/catkin_ws/src

Solution

1. Step 1: Understand the folder creation command

   The mkdir -p command creates the full directory path, including parent folders if missing.

2. Step 2: Identify the correct command for creating src inside catkin_ws

   mkdir -p ~/catkin_ws/src uses mkdir -p ~/catkin_ws/src, which creates both catkin_ws and src if needed.

3. Final Answer:

   mkdir -p ~/catkin_ws/src -> Option C

4. Quick Check:

   Use mkdir -p for nested folders [OK]

Hint: Use mkdir -p to create nested folders at once [OK]

Common Mistakes:

• Using mkdir without -p and missing parent folder
• Confusing catkin_make with mkdir
• Trying to source a folder instead of creating it

3. After creating your catkin workspace folder and src directory, what is the output of running catkin_make inside ~/catkin_ws?

medium

A. Error: src folder missing

B. Build successful with devel and build folders created

C. No output, command ignored

D. Workspace deleted

Solution

1. Step 1: Understand what catkin_make does

   It builds the packages inside the src folder and creates devel and build folders for development and build files.

2. Step 2: Predict output after running catkin_make in a valid workspace

   Since src exists, it will build successfully and create those folders.

3. Final Answer:

   Build successful with devel and build folders created -> Option B

4. Quick Check:

   catkin_make builds workspace and creates folders [OK]

Hint: catkin_make builds and creates devel/build folders [OK]

Common Mistakes:

• Expecting error if src exists
• Thinking catkin_make deletes workspace
• Assuming no output or ignored command

4. You created a catkin workspace but forgot to source the setup file. What problem will you face?

medium

A. catkin_make will fail with syntax errors

B. The workspace will delete itself automatically

C. Your system will crash

D. ROS commands and packages from your workspace won't be recognized

Solution

1. Step 1: Understand the role of sourcing the setup file

   Sourcing devel/setup.bash sets environment variables so ROS can find your workspace packages.

2. Step 2: Identify the effect of not sourcing

   Without sourcing, ROS commands won't find your workspace packages, so they won't be recognized.

3. Final Answer:

   ROS commands and packages from your workspace won't be recognized -> Option D

4. Quick Check:

   Source setup file to use workspace [OK]

Hint: Always source setup.bash to use your workspace [OK]

Common Mistakes:

• Thinking workspace deletes itself
• Expecting catkin_make syntax errors
• Assuming system crashes

5. You want to create a new catkin workspace named my_ws in your home directory and build it. Which sequence of commands is correct?

hard

A. mkdir -p ~/my_ws/src && cd ~/my_ws && catkin_make && source devel/setup.bash

B. cd ~/my_ws && mkdir src && catkin_make && source ~/my_ws/devel/setup.bash

C. mkdir ~/my_ws && catkin_make ~/my_ws/src && source ~/my_ws/setup.bash

D. mkdir -p ~/my_ws/src && catkin_make src && source ~/my_ws/devel/setup.bash

Solution

1. Step 1: Create workspace and src folder correctly

   Use mkdir -p ~/my_ws/src to create both folders at once.

2. Step 2: Navigate to workspace and build

   Change directory to ~/my_ws and run catkin_make to build the workspace.

3. Step 3: Source the setup file

   Source devel/setup.bash inside the workspace to use the built packages.

4. Final Answer:

   mkdir -p ~/my_ws/src && cd ~/my_ws && catkin_make && source devel/setup.bash -> Option A

5. Quick Check:

   Create src, build, source setup.bash [OK]

Hint: Create src, cd workspace, catkin_make, then source setup.bash [OK]

Common Mistakes:

• Running catkin_make outside workspace folder
• Not sourcing the correct setup file
• Using wrong paths in commands