Skip to content

Refactor #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
drymon merged 1 commit into from
Sep 11, 2026
Merged

Refactor #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Pinned build/test environment for dmosal.
#
# This image locks the exact toolchain package versions used to build, test,
# lint, and document the library, so `docker build` reproduces the same
# environment on any machine (and mirrors what CI resolves on ubuntu-22.04).
#
# Usage:
# docker build -t dmosal-dev .
# docker run --rm -it -v "$PWD":/workspace -w /workspace dmosal-dev bash
# # or, without an interactive shell:
# docker run --rm -v "$PWD":/workspace -w /workspace dmosal-dev just check
#
# To refresh pins (e.g. after a new Ubuntu 22.04 security update), run:
# docker run --rm ubuntu:22.04 bash -c \
# "apt-get update -qq && apt-cache policy <pkg1> <pkg2> ..."
# and update the versions below accordingly.

FROM ubuntu:22.04

ARG CMAKE_VERSION=3.22.1-1ubuntu1.22.04.2
ARG CMOCKA_VERSION=1.1.5-2
ARG DOXYGEN_VERSION=1.9.1-2ubuntu2
ARG GRAPHVIZ_VERSION=2.42.2-6ubuntu0.1
ARG CLANG_FORMAT_VERSION=1:14.0-55~exp2
ARG CLANG_TIDY_VERSION=1:14.0-55~exp2
ARG VALGRIND_VERSION=1:3.18.1-1ubuntu2
ARG LCOV_VERSION=1.15-1
ARG CPPCHECK_VERSION=2.7-1
ARG GCC_VERSION=4:11.2.0-1ubuntu1
ARG GXX_VERSION=4:11.2.0-1ubuntu1
ARG CLANG_VERSION=1:14.0-55~exp2

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates curl \
&& rm -rf /var/lib/apt/lists/*

RUN apt-get update && apt-get install -y --no-install-recommends \
cmake=${CMAKE_VERSION} \
libcmocka-dev=${CMOCKA_VERSION} \
doxygen=${DOXYGEN_VERSION} \
graphviz=${GRAPHVIZ_VERSION} \
clang-format=${CLANG_FORMAT_VERSION} \
clang-tidy=${CLANG_TIDY_VERSION} \
valgrind=${VALGRIND_VERSION} \
lcov=${LCOV_VERSION} \
cppcheck=${CPPCHECK_VERSION} \
gcc=${GCC_VERSION} \
g++=${GXX_VERSION} \
clang=${CLANG_VERSION} \
make \
git \
python3-pip \
&& rm -rf /var/lib/apt/lists/*

# just: pinned via its official install script + explicit tag, not apt
# (not packaged in the jammy repos).
ARG JUST_VERSION=1.36.0
RUN curl --proto '=https' --tlsv1.2 -sSf \
https://just.systems/install.sh \
| bash -s -- --tag ${JUST_VERSION} --to /usr/local/bin

# pre-commit: pinned exact version via pip.
ARG PRE_COMMIT_VERSION=3.7.1
RUN pip3 install --no-cache-dir "pre-commit==${PRE_COMMIT_VERSION}"

WORKDIR /workspace
149 changes: 26 additions & 123 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,9 @@
[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD--2--Clause-blue.svg)](LICENSE)
[![Language: C](https://img.shields.io/badge/language-C-brightgreen.svg)](#)

OSAL (OS Abstraction Layer) is a **lightweight, static resource allocation framework** designed for Real-Time Operating Systems (RTOS) in embedded systems. <br>
All OS resources are preconfigured within this framework, providing a seamless interface for managing tasks, semaphores, mutexes, timers, and more, all statically defined at initialization. <br>
Under the permissive BSD-2-Clause license, users can freely utilize and distribute the library without licensing complexities.

## Features

- **Static Resource Definition:** Allocate resources at initialization, promoting efficiency and predictability in resource-constrained environments.
- **Simple and Lightweight**: OSAL offers easily understandable source code and effortless integration into your application..
- **POSIX Compatibility:** Currently supports POSIX-based systems and designed for easy adaptation to other OS environments.
- **High Portability:** Flexible design facilitates adaptation to various RTOS and embedded platforms.
- **OS components:** Supports mutex, semaphore, task, timer and time.

## Usage
A small, portable embedded C abstraction layer providing deterministic/bounded
resource management and consistent concurrency, timing, and communication
semantics across POSIX and RTOS platforms. Licensed BSD-2-Clause.

```
+-------------------------------+
Expand All @@ -37,130 +27,43 @@ Under the permissive BSD-2-Clause license, users can freely utilize and distribu
+-------------------------------+
```

OSAL aims to enhance application code reliability by effectively managing OS resources,
ensuring portability across multiple operating systems.

## Prerequisites

On Ubuntu/Debian:

```
$ sudo apt install cmake libcmocka-dev doxygen
```

- `cmake` — build system.
- `libcmocka-dev` — test framework used by `make check`. Tested with libcmocka 1.1.5-2.
- `doxygen` — generates API documentation via `make doc`.
## Build & test

Optional, for local style/lint checks (see [Style checks](#style-checks) below):
Requires `cmake`, `libcmocka-dev`, `doxygen` (`sudo apt install cmake
libcmocka-dev doxygen` on Ubuntu/Debian).

```
$ sudo apt install clang-format python3-pip
$ pip install pre-commit
$ just check # configure + build + run tests
```

## Compilation

> **Quick start:** if you have [`just`](https://github.com/casey/just) installed,
> run `just build`, `just check`, `just check-valgrind`, etc. from the repo
> root — see the [`justfile`](justfile) for all available recipes. The steps
> below show the equivalent raw CMake commands.

- Build the lib:

```
$ mkdir build
$ cd build
$ cmake ..
$ make
```
No [`just`](https://github.com/casey/just)? See the [`justfile`](justfile)
for the equivalent raw `cmake`/`ctest` commands, or use the pinned
[`Dockerfile`](Dockerfile) for a reproducible toolchain
(`docker build -t dmosal-dev . && docker run --rm -v "$PWD":/workspace -w
/workspace dmosal-dev just check`).

You can configure OSAL resource limitations via the command line.
For detailed information on configuration parameters and how to set them up,
please consult the [osal_config.cmake](osal_config.cmake) file.

- Install the lib:

```
$ sudo make install # install into `/usr/local/`
```

- Uninstall the lib:

```
$ sudo make uninstall # uninstall
```

## Test

The test can be run after the compilation steps above:

```
$ make check
```
Other recipes: `just check-valgrind`, `just check-asan`, `just check-tsan`,
`just check-coverage`, `just doc`, `just format`, `just tidy` — run `just
--list` for the full set.

Or simply `just check` from the repo root.
Resource limits (max tasks, queues, etc.) are configured at CMake time; see
[osal_config.cmake](osal_config.cmake).

## Examples

Please refer to the `examples` dir for how to use the OSAL APIs.
See [examples/](examples/) for sample programs. Build with `just build`
(CMake target `examples`).

The examples code can be built as:
## Documentation

```
$ make examples
```

## Style checks

Style is described by `.clang-format` at the repo root. CI enforces it, but
you can check locally too.

- Check without changing files:

```
$ git ls-files '*.c' '*.h' | grep -v '\.in$' | xargs clang-format --dry-run -Werror
```

- Auto-format in place:

```
$ git ls-files '*.c' '*.h' | grep -v '\.in$' | xargs clang-format -i
```

Optional `pre-commit` hooks (trailing whitespace, EOL fixer, clang-format,
etc.) are configured in `.pre-commit-config.yaml`. To enable them:
- API reference (Doxygen): `just doc`, output in `build/doc/html/`.
- Design/behavioral docs: [docs/](docs/README.md) (architecture, API spec,
resource lifetime, thread-safety, porting guide).

```
$ pre-commit install # run hooks automatically on `git commit`
$ pre-commit run --all-files # run once against the whole tree
```

**If a pre-commit hook fails on `git commit`:** most hooks auto-fix the files
(clang-format, trailing whitespace, end-of-file). Just re-stage and commit again:

```
$ git commit -m "..." # hook edits some files and blocks the commit
$ git add -u # re-stage the hook's fixes
$ git commit -m "..." # commit succeeds
```

## Doc
## Contributing

Design and behavioral documentation (architecture, API spec, resource
lifetime, thread-safety, porting guide) lives in [docs/](docs/README.md).

To generate the Doxygen API reference, execute the following command.
The output can be located in the build directory.

```
$ make doc
```
See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

This library is licensed under the BSD-2-Clause license. See the LICENSE file for details.

## Contributions

Contributions are welcome! If you find any bugs or have suggestions for improvements, feel free to open an issue or create a pull request.
BSD-2-Clause — see [LICENSE](LICENSE).
Loading