diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..c2f83c6 --- /dev/null +++ b/Dockerfile @@ -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 ..." +# 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 diff --git a/README.md b/README.md index 62c6d45..19438b7 100644 --- a/README.md +++ b/README.md @@ -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.
-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.
-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. ``` +-------------------------------+ @@ -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).