# How to build a Freestanding Zephyr Application

<div style="background: linear-gradient(135deg, #2C3E50, #4CA1AF); padding: 20px; border-radius: 8px; color: white; margin: 20px 0; text-align: center;">
<h2 style="margin: 0; color: white;">🚀 Breaking Free from the Zephyr Tree Structure</h2>
<p style="margin: 10px 0 0 0; opacity: 0.9;">Learn how to create independent, maintainable embedded projects that stand on their own</p>

<img src="https://hackmd.io/_uploads/BJA8GIYtle.jpg" alt="zephyr-logo" style="margin-top: 20px; max-width: 100%; height: auto; border-radius: 6px;" />
</div>

Ever come across a zephyr project that is under a nested folder structure and wonder how you would build the application? What if I told you that it is not as challenging as you might think?
Yes, that’s right, you can actually build a zephyr project outside the zephyr workspace. There is a catch though, you need to have installed zephyr already in your computer.

I will demonstrate how to do it on Ubuntu. Visit the zephyr official website referenced below and make sure to follow all the steps of installing Zephyr on your computer. After doing that, we jump to the next step.

## What is a Freestanding Zephyr Application?

A freestanding Zephyr application lives outside the main Zephyr source tree. Instead of working under `zephyr/samples`, your project maintains its own repo, structure, and build configuration.

**Benefits:**

* Independent version control
* Cleaner collaboration and CI pipelines
* Better code reuse across projects
* Straightforward licensing/IP separation
* Easier portability to new boards

If you consider it, it is the professional way to structure an embedded project.

## Prerequisites: How to set Up Your Development Environment

I will demonstrate how to do it on Ubuntu. Visit the zephyr official website [official zephyr installataion guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html) and make sure to follow all the steps of installing Zephyr SDK, Python dependencies and build tools on your computer(Ubuntu is recommended).

This directory will be generated`~/zephyrproject`

After doing that, we jump to the next step.

## Creating Your First Freestanding Project

<div style="background: linear-gradient(135deg, #0072ff, #00c6ff); padding: 15px; border-radius: 6px; color: white; margin: 20px 0;">
<h3 style="margin: 0 0 10px 0; color: white;">💡 Pro Tip</h3>
<p style="margin: 0; opacity: 0.9;">Start with a simple Hello World to confirm your setup before scaling up.</p>
</div>

**Project structure:**

hello_world_standalone/
├── src/
│   └── main.c
├── CMakeLists.txt
└── prj.conf

**main.c**

#include <zephyr/kernel.h>
#include <zephyr/sys/printk.h>

int main(void)
{
    printk("Hello World! Running on %s\\n", CONFIG_BOARD_TARGET);
    printk("Freestanding Zephyr App Started!\\n");
    printk("System uptime: %lld ms\\n", k_uptime_get());
    return 0;
}

**CMakeLists.txt**

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(hello_world_standalone)
target_sources(app PRIVATE src/main.c)

**prj.conf**

CONFIG_SERIAL=y
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y

## Building and Running

<div style="background: linear-gradient(135deg, #FF416C, #FF4B2B); padding: 15px; border-radius: 6px; color: white; margin: 20px 0;">
<h3 style="margin: 0 0 10px 0; color: white;">⚡ Quick Start</h3>
<p style="margin: 0; opacity: 0.9;">You must activate the Zephyr environment each time you build a freestanding application.</p>
</div>

### 1. Activate the Zephyr Environment

Navigate to your project folder and activate the Python virtual environment **and** the Zephyr environment:

cd hello_world_standalone
source ~/zephyrproject/.venv/bin/activate
source ~/zephyrproject/zephyr/zephyr-env.sh 

Please note that you have to always run that last command everytime you open the project folder in order to build it.

### 2. Build the Application

west build -b rpi_pico . -p always

Switch the `-b` parameter to target any Zephyr-supported board.

## Troubleshooting Common Issues

* **Missing environment vars** → Ensure `ZEPHYR_BASE` and Python venv are activated.
* **CMake errors** → Check `find_package(Zephyr ...)` in `CMakeLists.txt`.
* **Path issues (esp. Windows)** → Stick to recommended structures and run commands from project root.

## Why This Matters

<div style="background: linear-gradient(135deg, #6a11cb, #2575fc); padding: 15px; border-radius: 6px; color: white; margin: 20px 0;">
<h3 style="margin: 0 0 10px 0; color: white;">🏢 Professional Insight</h3>
<p style="margin: 0; opacity: 0.9;">Freestanding apps align with industry best practices in embedded systems.</p>
</div>

Freestanding projects:

* Keep your codebase cleanly separated from Zephyr
* Simplify collaboration and reviews
* Improve IP management for commercial work
* Make porting to new hardware straightforward

## What’s Next

This Hello World example proves your setup works. In the next post, we’ll scale to a real-world use case: building an ADC monitoring system with an OLED display. You’ll see how freestanding projects handle multiple peripherals, real-time data, and user interfaces—all while keeping structure clean and maintainable.

---

*Stay tuned: we’ll go from “Hello World” to real-world embedded systems, one step at a time.*