Skip to content

docs: Prioritize installation options in README #28

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
Vladush merged 2 commits into from
Feb 17, 2026
Merged

docs: Prioritize installation options in README #28

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7e41ca4
docs: Refactor README installation section for better UX
Vladush Feb 1, 2026
e339cd1
Merge branch 'master' into feat/prevent-master-pushes
Vladush Feb 1, 2026
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
74 changes: 39 additions & 35 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,41 +43,6 @@ Since open-sourcing, I've put effort into making it hardware-agnostic and well-d

## Installation

### Build Dependencies

> **Don't panic!** You don't need to manually install these. The provided script `scripts/install_deps.sh` will automatically install everything you need. This list is just for reference or for those building manually.

These are required to **compile** the project from source (Options A & B).

| Package | Purpose |
| :--------------------------- | :------------------------------------------ |
| `cmake`, `build-essential` | Build system |
| `libpam0g-dev` | PAM module development headers |
| `v4l-utils` | Camera detection tools (also a runtime dep) |
| `curl` / `wget` | Downloading models and dependencies |
| `ninja-build` *(optional)* | Faster builds (recommended) |

> **Runtime Dependencies**: If you are installing a pre-built `.deb` package, the package manager (`apt`/`dpkg`) will automatically install the necessary runtime libraries (e.g., `libpam0g`, `libatlas3-base`). You do **not** need the `-dev` development headers for running the software.
>
> **Build System Note:** The install scripts use `make` by default. If you have `ninja-build` installed, you can use Ninja for faster incremental builds:
>
> ```bash
> cmake -G Ninja ..
> ninja
> ```

**Compiler Compatibility:** The project is C++17 compliant. While we strictly verify on **Ubuntu 24.04**, the codebase includes polyfills (e.g., `<charconv>` fallbacks) to support older compilers found in **Ubuntu 20.04 LTS (GCC 9)** and Debian 11.

| Architecture | Compiler | Status | Notes |
| :----------- | :---------- | :------------ | :--------------------------- |
| **x86_64** | GCC 9+ | ✅ Compatible | Ubuntu 20.04+ / Debian 11+ |
| **x86_64** | GCC 11+ | ✅ Verified | Ubuntu 22.04+ / Debian 12+ |
| **x86_64** | Clang 10+ | ✅ Compatible | Ubuntu 20.04+ |
| **AARCH64** | GCC (Cross) | ✅ Verified | via Docker/QEMU |
| **RISC-V** | GCC (Cross) | ✅ Verified | via Docker/QEMU |

> **Note**: We now compile a **static version of OpenCV 4.12.0** automatically. You do **not** need to install `libopencv-dev` or generic system libraries anymore. This ensures the authentication service runs reliably regardless of your OS version.

### Option A: Install from Package (Recommended)

If you have downloaded a release file (`.deb`), installation is extremely simple:
Expand Down Expand Up @@ -142,6 +107,45 @@ sudo apt install ./linuxcampam_*.deb

The package installation will automatically backup your PAM config, configure the cameras, and enable the module.

### Build Dependencies & Compatibility

#### Build Dependencies

> **Don't panic!** You don't need to manually install these. The provided script `scripts/install_deps.sh` will automatically install everything you need. This list is just for reference or for those building manually.

These are required to **compile** the project from source (Options B & C).

| Package | Purpose |
| :--------------------------- | :------------------------------------------ |
| `cmake`, `build-essential` | Build system |
| `libpam0g-dev` | PAM module development headers |
| `v4l-utils` | Camera detection tools (also a runtime dep) |
| `curl` / `wget` | Downloading models and dependencies |
| `ninja-build` *(optional)* | Faster builds (recommended) |

> **Runtime Dependencies**: If you are installing a pre-built `.deb` package, the package manager (`apt`/`dpkg`) will automatically install the necessary runtime libraries (e.g., `libpam0g`, `libatlas3-base`). You do **not** need the `-dev` development headers for running the software.
>
> **Build System Note:** The install scripts use `make` by default. If you have `ninja-build` installed, you can use Ninja for faster incremental builds:
>
> ```bash
> cmake -G Ninja ..
> ninja
> ```

#### Compiler Compatibility

The project is C++17 compliant. While we strictly verify on **Ubuntu 24.04**, the codebase includes polyfills (e.g., `<charconv>` fallbacks) to support older compilers found in **Ubuntu 20.04 LTS (GCC 9)** and Debian 11.

| Architecture | Compiler | Status | Notes |
| :----------- | :---------- | :------------ | :--------------------------- |
| **x86_64** | GCC 9+ | ✅ Compatible | Ubuntu 20.04+ / Debian 11+ |
| **x86_64** | GCC 11+ | ✅ Verified | Ubuntu 22.04+ / Debian 12+ |
| **x86_64** | Clang 10+ | ✅ Compatible | Ubuntu 20.04+ |
| **AARCH64** | GCC (Cross) | ✅ Verified | via Docker/QEMU |
| **RISC-V** | GCC (Cross) | ✅ Verified | via Docker/QEMU |

> **Note**: We now compile a **static version of OpenCV 4.12.0** automatically. You do **not** need to install `libopencv-dev` or generic system libraries anymore. This ensures the authentication service runs reliably regardless of your OS version.

## Configuration

The configuration file is at `/etc/linuxcampam/config.ini`.
Expand Down