mirror of
https://github.com/rsyslog/rsyslog.git
synced 2026-03-19 14:09:30 +01:00
chore: add project-wide formatting and editor configs
- add .editorconfig for indent, whitespace, and file-type rules - add project-local .vimrc to enforce Vim settings via exrc - add .clang-format for C/C++ style presets and list formatting - add devtools/format-code.sh to run clang-format and fixups - adjust clang-format config for stable, idempotent output - update AGENTS.md with new formatting strategy - add .git-blame-ignore-revs entry for format change commit This commit sets up an automated formatting pipeline to let contributors use their editor of choice while ensuring consistent, stable code style across the project.
This commit is contained in:
Rainer Gerhards
parent
4eb2674269
commit
786ea7c92f
43
.clang-format
Normal file
43
.clang-format
Normal file
@ -0,0 +1,43 @@
|
||||
# Base on Google’s K&R-style preset (Attach braces, indent case labels, etc.)
|
||||
BasedOnStyle: Google
|
||||
|
||||
# Switch from tabs to spaces (4 spaces per level)
|
||||
IndentWidth: 4
|
||||
TabWidth: 4
|
||||
UseTab: Never
|
||||
|
||||
# Ensure pointer stars stay next to the type, as in rsyslog’s declarations
|
||||
PointerAlignment: Left
|
||||
|
||||
# Keep case labels indented under switch
|
||||
IndentCaseLabels: true
|
||||
|
||||
# Continuation lines (e.g. broken calls) also align with 4 spaces
|
||||
ContinuationIndentWidth: 4
|
||||
|
||||
# Pack function parameters onto one line when they fit
|
||||
#BinPackParameters: true
|
||||
BinPackParameters: false
|
||||
BinPackArguments: true
|
||||
AlignAfterOpenBracket: Align
|
||||
|
||||
# Don’t realign or sort existing trailing comments or includes
|
||||
AlignTrailingComments: false
|
||||
SortIncludes: false
|
||||
|
||||
# Prevent short functions or blocks being reformatted into a single line
|
||||
AllowShortFunctionsOnASingleLine: Empty
|
||||
AllowShortBlocksOnASingleLine: false
|
||||
|
||||
# Turn off automatic re-wrapping so long comment lines aren’t split
|
||||
ColumnLimit: 120
|
||||
|
||||
# Special handling for some generative macros
|
||||
MacroBlockBegin: "^BEGIN"
|
||||
MacroBlockEnd: "^END"
|
||||
|
||||
|
||||
MaxEmptyLinesToKeep: 2
|
||||
# tells clang-format to indent the whole line – # and all – to the current code indent
|
||||
IndentPPDirectives: BeforeHash
|
||||
AlignEscapedNewlines: Left
|
||||
39
.editorconfig
Normal file
39
.editorconfig
Normal file
@ -0,0 +1,39 @@
|
||||
|
||||
# EditorConfig is awesome: https://EditorConfig.org
|
||||
root = true
|
||||
|
||||
# Default for all files
|
||||
[*]
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
trim_trailing_whitespace = true
|
||||
insert_final_newline = true
|
||||
end_of_line = lf
|
||||
|
||||
# Makefiles use hard tabs
|
||||
[Makefile]
|
||||
indent_style = tab
|
||||
|
||||
# Autoconf scripts & shell files
|
||||
[*.{ac,am,sh}]
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
|
||||
# C/C++ source and headers
|
||||
[*.{c,cpp,h,hpp}]
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
|
||||
# Python
|
||||
[*.py]
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
|
||||
# YAML/Ansible/CI files
|
||||
[*.{yml,yaml}]
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
|
||||
# Markdown/text—don’t trim here
|
||||
[*.{md,txt}]
|
||||
trim_trailing_whitespace = false
|
||||
1
.git-blame-ignore-revs
Normal file
1
.git-blame-ignore-revs
Normal file
@ -0,0 +1 @@
|
||||
b326c76f453814dae91d7d9974df88129c861507
|
||||
28
.vimrc
Normal file
28
.vimrc
Normal file
@ -0,0 +1,28 @@
|
||||
" ====================================================================
|
||||
" Project‑local Vim settings for rsyslog
|
||||
" (drop this file as .vimrc or .exrc in the project root)
|
||||
" ====================================================================
|
||||
|
||||
" Use spaces, no tabs
|
||||
setlocal expandtab
|
||||
setlocal shiftwidth=4
|
||||
setlocal softtabstop=4
|
||||
setlocal tabstop=4
|
||||
|
||||
" Trim trailing whitespace on save
|
||||
autocmd BufWritePre * :%s/\s\+$//e
|
||||
|
||||
" File‑type specific overrides:
|
||||
|
||||
" Makefiles always use actual tabs
|
||||
autocmd FileType make setlocal noexpandtab
|
||||
|
||||
" Shell and autoconf scripts: 2‑space indent
|
||||
autocmd FileType sh,autoconf setlocal expandtab shiftwidth=2 softtabstop=2 tabstop=2
|
||||
|
||||
" YAML/CI files: 2‑space indent
|
||||
autocmd FileType yaml setlocal expandtab shiftwidth=2 softtabstop=2 tabstop=2
|
||||
|
||||
" Python: 4‑space indent (already default above, but explicit here)
|
||||
autocmd FileType python setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=4
|
||||
|
||||
356
AGENTS.md
356
AGENTS.md
@ -2,92 +2,109 @@
|
||||
|
||||
This file defines guidelines and instructions for AI assistants (e.g., Codex, GitHub Copilot Workspace, ChatGPT agents) to understand and contribute effectively to the rsyslog codebase.
|
||||
|
||||
---
|
||||
|
||||
## Repository Overview
|
||||
|
||||
- **Primary Language**: C
|
||||
- **Build System**: autotools (`autogen.sh`, `configure`, `make`)
|
||||
- **Modules**: Dynamically loaded from `modules/`
|
||||
- **Contributions**: Additional modules and features are placed in `contrib/`, which contains community-contributed plugins not actively maintained by the core rsyslog team. These are retained in `contrib/` even if adopted later, to avoid disruptions in dependent software.
|
||||
- **Documentation**: Maintained in the doc/ subdirectory
|
||||
- **Child Projects**:
|
||||
- [`rsyslog-docker`](https://github.com/rsyslog/rsyslog-docker): Provides prebuilt container environments for development and CI
|
||||
- **Side Libraries** (each in its own repo within the rsyslog GitHub org):
|
||||
- [`liblognorm`](https://github.com/rsyslog/liblognorm)
|
||||
- [`librelp`](https://github.com/rsyslog/librelp)
|
||||
- [`libestr`](https://github.com/rsyslog/libestr)
|
||||
- [`libfastjson`](https://github.com/rsyslog/libfastjson): A fork of libfastjson by the rsyslog project, optimized for speed. This library is used by multiple external projects.
|
||||
- **Primary Language**: C
|
||||
- **Build System**: autotools (`autogen.sh`, `configure`, `make`)
|
||||
- **Modules**: Dynamically loaded from `modules/`
|
||||
- **Contributions**: Additional modules and features are placed in `contrib/`, which contains community-contributed plugins not actively maintained by the core rsyslog team. These are retained in `contrib/` even if adopted later, to avoid disruptions in dependent software.
|
||||
- **Documentation**: Maintained in the doc/ subdirectory
|
||||
- **docker definitions**: Maintained in the packaging/docker/ subdirectory
|
||||
- **Side Libraries** (each in its own repo within the rsyslog GitHub org):
|
||||
- [`liblognorm`](https://github.com/rsyslog/liblognorm)
|
||||
- [`librelp`](https://github.com/rsyslog/librelp)
|
||||
- [`libestr`](https://github.com/rsyslog/libestr)
|
||||
- [`libfastjson`](https://github.com/rsyslog/libfastjson): A fork of libfastjson by the rsyslog project, optimized for speed. This library is used by multiple external projects.
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
## Automated Formatting Normalization Strategy
|
||||
|
||||
We treat formatting as a normalization step, not a developer-side constraint.
|
||||
AI agents should follow this process:
|
||||
|
||||
1. Canonical formatting via clang-format
|
||||
Use the Google-style base with 4-space indentation in .clang-format.
|
||||
|
||||
2. Helper-based normalization
|
||||
Run devtools/format-code.sh to run clang-format and potential helper scripts.
|
||||
|
||||
3. Developer freedom & accessibility
|
||||
Local formatting is unrestricted; only normalized output matters.
|
||||
|
||||
4. CI enforcement & maintainer assist
|
||||
CI checks formatting; maintainers may edit PRs directly.
|
||||
|
||||
5. Git blame hygiene
|
||||
Formatting-only commits listed in .git-blame-ignore-revs.
|
||||
|
||||
AI Agent Note: run devtools/format-code.sh as the final formatting step before commit.
|
||||
-----
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Base Repository
|
||||
- URL: https://github.com/rsyslog/rsyslog
|
||||
- **Default base branch: `master`**
|
||||
> For technical reasons, `master` is still the default branch. Numerous scripts and CI workflows rely on this name.
|
||||
|
||||
- URL: [https://github.com/rsyslog/rsyslog](https://github.com/rsyslog/rsyslog)
|
||||
- **Default base branch: `master`**
|
||||
> For technical reasons, `master` is still the default branch. Numerous scripts and CI workflows rely on this name.
|
||||
|
||||
### Contributor Workflow
|
||||
1. Fork the repository (for personal development)
|
||||
2. Create a feature/fix branch
|
||||
3. Push changes to your fork
|
||||
4. Open a **pull request directly into `rsyslog/rsyslog:master`**
|
||||
|
||||
1. Fork the repository (for personal development)
|
||||
2. Create a feature/fix branch
|
||||
3. Push changes to your fork
|
||||
4. Open a **pull request directly into `rsyslog/rsyslog:master`**
|
||||
|
||||
> **Important**: AI-generated PRs must target the `rsyslog/rsyslog` repository directly.
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
## Branch Naming Conventions
|
||||
|
||||
There are no strict naming rules, but these conventions are used frequently:
|
||||
|
||||
- For issue-based work: `i-<issue-number>` (e.g., `i-2245`)
|
||||
- For features or refactoring: free-form is acceptable
|
||||
- For AI-generated work: prefix the branch name with the AI tool name
|
||||
(e.g., `gpt-i-2245-json-stats-export`)
|
||||
- For issue-based work: `i-<issue-number>` (e.g., `i-2245`)
|
||||
- For features or refactoring: free-form is acceptable
|
||||
- For AI-generated work: prefix the branch name with the AI tool name
|
||||
(e.g., `gpt-i-2245-json-stats-export`)
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
## Coding Standards
|
||||
|
||||
- Commit messages **must include all relevant information**, not just in the PR
|
||||
- Commit message titles **must not exceed 70 characters**
|
||||
- commit message text must be plain US ASCII, line length must not exceed 86 characters
|
||||
- When referencing GitHub issues, use the **full GitHub URL** to assist in `git log`-based reviews
|
||||
- Favor **self-documenting code** over excessive inline comments
|
||||
- Public functions should use Doxygen-style comments
|
||||
- See `COMMENTING_STYLE.md` for detailed Doxygen guidelines
|
||||
- Modules must implement and register `modInit()` and `modExit()`
|
||||
- Commit messages **must include all relevant information**, not just in the PR
|
||||
- Commit message titles **must not exceed 70 characters**
|
||||
- commit message text must be plain US ASCII, line length must not exceed 86 characters
|
||||
- When referencing GitHub issues, use the **full GitHub URL** to assist in `git log`-based reviews
|
||||
- Favor **self-documenting code** over excessive inline comments
|
||||
- Public functions should use Doxygen-style comments
|
||||
- See `COMMENTING_STYLE.md` for detailed Doxygen guidelines
|
||||
- Modules must implement and register `modInit()` and `modExit()`
|
||||
|
||||
When fixing compiler warnings like `stringop-overread`, explain in the commit message:
|
||||
- Why the warning occurred
|
||||
- What part of the code was changed
|
||||
- How the fix prevents undefined behavior or aligns with compiler expectations
|
||||
- Optionally link: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wstringop-overread
|
||||
|
||||
### Indentation Rules (Language-Specific)
|
||||
- Why the warning occurred
|
||||
- What part of the code was changed
|
||||
- How the fix prevents undefined behavior or aligns with compiler expectations
|
||||
- Optionally link: [https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wstringop-overread](https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wstringop-overread)
|
||||
|
||||
- **C / Header / Makefiles**:
|
||||
- Preferred: **tabs only** for indentation (`\t`)
|
||||
- Acceptable: **spaces** may be used if required by the generation tool
|
||||
- Do **not** mix tabs and spaces in the same block
|
||||
- The **only allowed space at column 1** is for multiline comments starting with ` *`, e.g.:
|
||||
```c
|
||||
/*
|
||||
* This is a valid Doxygen or traditional comment.
|
||||
*/
|
||||
```
|
||||
-----
|
||||
|
||||
- **Python**:
|
||||
- Follow [PEP 8](https://peps.python.org/pep-0008/): **4 spaces per indent level**
|
||||
- Do **not** use tabs in `.py` files
|
||||
## Editor & Formatting Configuration
|
||||
|
||||
> AI Agent Note:
|
||||
> When generating C code, tabs are preferred. If your environment requires spaces,
|
||||
> simulate tab width of 8 spaces for proper alignment.
|
||||
The repository includes:
|
||||
|
||||
---
|
||||
- `.editorconfig`: Editor-agnostic indent, whitespace, EOL, and file-type rules.
|
||||
- Project `.vimrc`/`.exrc`: Vim settings when `set exrc secure` is enabled.
|
||||
- `.clang-format`: Canonical C/C++ style; run `clang-format -i -style=file`.
|
||||
- `devtools/format-code.sh`: Runs clang-format plus helper fixups.
|
||||
|
||||
Editors and IDEs with EditorConfig support (VS Code, JetBrains, Sublime, Vim, Emacs)
|
||||
will automatically apply these rules.
|
||||
|
||||
-----
|
||||
|
||||
## Build & Test Expectations
|
||||
|
||||
@ -95,46 +112,47 @@ Whenever `.c` or `.h` files are modified, a build should be performed using `mak
|
||||
If new functionality is introduced, at least a basic test should be created and run.
|
||||
|
||||
If possible, agents should:
|
||||
- Build the project using `./configure` and `make`
|
||||
- Run an individual test using the instructions below
|
||||
|
||||
- Build the project using `./configure` and `make`
|
||||
- Run an individual test using the instructions below
|
||||
|
||||
> In restricted environments, a build may not be possible. In such cases, ensure the
|
||||
> generated code is clear and well-commented to aid review.
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
## Testing & Validation
|
||||
|
||||
All test definitions live under the `tests/` directory and are driven by the `tests/diag.sh` framework. In CI, `make check` remains the canonical way to run the full suite; **AI agents should avoid invoking `make check` by default**, because:
|
||||
|
||||
- It wraps all tests in a harness that hides stdout/stderr on failure
|
||||
- It requires parsing `tests/test-suite.log` for details
|
||||
- It can take 10+ minutes and consume significant resources
|
||||
- It wraps all tests in a harness that hides stdout/stderr on failure
|
||||
- It requires parsing `tests/test-suite.log` for details
|
||||
- It can take 10+ minutes and consume significant resources
|
||||
|
||||
Instead, AI agents should invoke individual test scripts directly. This yields unfiltered output and immediate feedback, without the CI harness. The `diag.sh` framework now builds any required test support automatically, so there is **no longer** a need for a separate “build core components” step.
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
### Running Individual Tests (AI-Agent Best Practice)
|
||||
|
||||
1. **Configure the project** (once per session):
|
||||
```bash
|
||||
./configure --enable-imdiag --enable-testbench
|
||||
```
|
||||
2. **Invoke your test**:
|
||||
```bash
|
||||
./tests/<test-script>.sh
|
||||
```
|
||||
For example:
|
||||
```bash
|
||||
./tests/manytcp-too-few-tls-vg.sh > /tmp/test.log && tail -n20 /tmp/test.log
|
||||
```
|
||||
3. **Why this works**
|
||||
- Each test script transparently finds and loads the test harness
|
||||
- You get unfiltered stdout/stderr without any CI wrapper
|
||||
- No manual `cd` or log-file parsing required
|
||||
1. **Configure the project** (once per session):
|
||||
```bash
|
||||
./configure --enable-imdiag --enable-testbench
|
||||
```
|
||||
2. **Invoke your test**:
|
||||
```bash
|
||||
./tests/<test-script>.sh
|
||||
```
|
||||
For example:
|
||||
```bash
|
||||
./tests/manytcp-too-few-tls-vg.sh > /tmp/test.log && tail -n20 /tmp/test.log
|
||||
```
|
||||
3. **Why this works**
|
||||
- Each test script transparently finds and loads the test harness
|
||||
- You get unfiltered stdout/stderr without any CI wrapper
|
||||
- No manual `cd` or log-file parsing required
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
### Full Test Suite (CI-Only)
|
||||
|
||||
@ -145,23 +163,23 @@ For continuous-integration pipelines or when you need to validate the entire sui
|
||||
make check
|
||||
```
|
||||
|
||||
- To limit parallelism (avoid flaky failures), pass `-j2` or `-j4` to `make`.
|
||||
- If a failure occurs, inspect `tests/test-suite.log` for detailed diagnostics.
|
||||
- To limit parallelism (avoid flaky failures), pass `-j2` or `-j4` to `make`.
|
||||
- If a failure occurs, inspect `tests/test-suite.log` for detailed diagnostics.
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
### Test Environment
|
||||
|
||||
Human developers may reproduce CI conditions using the official container images from [`rsyslog/rsyslog-docker`](https://github.com/rsyslog/rsyslog-docker). For single-test runs, `rsyslog/rsyslog_dev_base_ubuntu:24.04` is recommended—but **AI agents should not attempt to pull or run these images**. They must use the standard configure + direct-test workflow inside their existing container.
|
||||
Human developers can replicate CI conditions using the official container images available on **Docker Hub**. For single-test runs, we recommend `rsyslog/rsyslog_dev_base_ubuntu:24.04`. Please note that **AI agents should not attempt to pull or run these images**. Instead, they should utilize the standard configure + direct-test workflow within their existing container environment.
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
## Manual Setup (discouraged)
|
||||
|
||||
Minimum setup requires:
|
||||
|
||||
- Autotools toolchain: `autoconf`, `automake`, `libtool`, `make`, `gcc`
|
||||
- Side libraries: `libestr`, `librelp`, `libfastjson`, `liblognorm` (must be installed or built manually)
|
||||
- Autotools toolchain: `autoconf`, `automake`, `libtool`, `make`, `gcc`
|
||||
- Side libraries: `libestr`, `librelp`, `libfastjson`, `liblognorm` (must be installed or built manually)
|
||||
|
||||
Example commands:
|
||||
|
||||
@ -174,145 +192,175 @@ make check
|
||||
|
||||
Use `make check -j2` or `-j4` max for reliability.
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
### Codex Build Environment Setup
|
||||
|
||||
Codex-based agents must only perform this setup **if a compile or test is required** (e.g., not for review-only tasks):
|
||||
|
||||
- Run this setup script to install core dependencies:
|
||||
```bash
|
||||
./devtools/codex-setup.sh
|
||||
```
|
||||
- Then, always run:
|
||||
```bash
|
||||
./autogen.sh
|
||||
```
|
||||
- Run this setup script to install core dependencies:
|
||||
```bash
|
||||
./devtools/codex-setup.sh
|
||||
```
|
||||
- Then, always run:
|
||||
```bash
|
||||
./autogen.sh
|
||||
```
|
||||
|
||||
This ensures Codex can build core components even in constrained environments. Skipping setup when not needed (e.g., code review) saves significant execution time.
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
## Module-Specific Capabilities
|
||||
|
||||
### `omelasticsearch`
|
||||
- Buildable: Yes, even in minimal environments
|
||||
- Depends on: `libcurl`
|
||||
- Testable: No. Tests require a running Elasticsearch instance and are skipped in Codex or constrained environments
|
||||
|
||||
- Buildable: Yes, even in minimal environments
|
||||
- Depends on: `libcurl`
|
||||
- Testable: No. Tests require a running Elasticsearch instance and are skipped in Codex or constrained environments
|
||||
|
||||
### `imjournal`
|
||||
- Buildable: Yes
|
||||
- Depends on: `libsystemd`
|
||||
- Testable: No. Requires journald-related libraries and a systemd journal service context not present in the Codex container
|
||||
|
||||
- Buildable: Yes
|
||||
- Depends on: `libsystemd`
|
||||
- Testable: No. Requires journald-related libraries and a systemd journal service context not present in the Codex container
|
||||
|
||||
### `imkafka` and `omkafka`
|
||||
- Depends on: `librdkafka` (plus `liblz4` when linking statically)
|
||||
|
||||
- Depends on: `librdkafka` (plus `liblz4` when linking statically)
|
||||
|
||||
### `fmpcre`
|
||||
- Buildable: Yes when `libpcre3-dev` (or equivalent) is installed
|
||||
- Testable: Yes, simple regression test `ffmpcre-basic.sh` exercises `pcre_match()`
|
||||
|
||||
- Buildable: Yes when `libpcre3-dev` (or equivalent) is installed
|
||||
- Testable: Yes, simple regression test `ffmpcre-basic.sh` exercises `pcre_match()`
|
||||
|
||||
### `omhiredis` and `imhiredis`
|
||||
- Depends on: `hiredis`; `imhiredis` also needs `libevent`
|
||||
|
||||
- Depends on: `hiredis`; `imhiredis` also needs `libevent`
|
||||
|
||||
### `ommongodb`
|
||||
- Depends on: `libmongoc-1.0`
|
||||
|
||||
- Depends on: `libmongoc-1.0`
|
||||
|
||||
### `omamqp1` and `omazureeventhubs`
|
||||
- Depends on: `libqpid-proton` (Azure module additionally needs `libqpid-proton-proactor`)
|
||||
|
||||
- Depends on: `libqpid-proton` (Azure module additionally needs `libqpid-proton-proactor`)
|
||||
|
||||
### `imhttp`
|
||||
- Depends on: `civetweb` and `apr-util`
|
||||
|
||||
- Depends on: `civetweb` and `apr-util`
|
||||
|
||||
### `imdocker`
|
||||
- Depends on: `libcurl` (>= 7.40.0)
|
||||
|
||||
- Depends on: `libcurl` (\>= 7.40.0)
|
||||
|
||||
### `impcap`
|
||||
- Depends on: `libpcap`
|
||||
|
||||
- Depends on: `libpcap`
|
||||
|
||||
### `imczmq` and `omczmq`
|
||||
- Depends on: `libczmq` (>= 4.0.0)
|
||||
|
||||
- Depends on: `libczmq` (\>= 4.0.0)
|
||||
|
||||
### `omrabbitmq`
|
||||
- Depends on: `librabbitmq` (>= 0.2.0)
|
||||
|
||||
- Depends on: `librabbitmq` (\>= 0.2.0)
|
||||
|
||||
### `omdtls` and `imdtls`
|
||||
- Depends on: `openssl` (>= 1.0.2 for output, >= 1.1.0 for input)
|
||||
|
||||
- Depends on: `openssl` (\>= 1.0.2 for output, \>= 1.1.0 for input)
|
||||
|
||||
### `omhttp`
|
||||
- Depends on: `libcurl`
|
||||
|
||||
- Depends on: `libcurl`
|
||||
|
||||
### `omhttpfs`
|
||||
- Depends on: `libcurl`
|
||||
|
||||
- Depends on: `libcurl`
|
||||
|
||||
### `mmnormalize`
|
||||
- Depends on: `liblognorm` (>= 2.0.3)
|
||||
|
||||
- Depends on: `liblognorm` (\>= 2.0.3)
|
||||
|
||||
### `mmkubernetes`
|
||||
- Depends on: `libcurl` and `liblognorm` (>= 2.0.3)
|
||||
|
||||
- Depends on: `libcurl` and `liblognorm` (\>= 2.0.3)
|
||||
|
||||
### `mmgrok`
|
||||
- Depends on: `grok` and `glib-2.0`
|
||||
|
||||
- Depends on: `grok` and `glib-2.0`
|
||||
|
||||
### `mmdblookup`
|
||||
- Depends on: `libmaxminddb` (dummy module built if absent)
|
||||
|
||||
- Depends on: `libmaxminddb` (dummy module built if absent)
|
||||
|
||||
### `omlibdbi`
|
||||
- Depends on: `libdbi`
|
||||
|
||||
- Depends on: `libdbi`
|
||||
|
||||
### `ommysql`
|
||||
- Depends on: `mysqlclient` via `mysql_config`
|
||||
|
||||
- Depends on: `mysqlclient` via `mysql_config`
|
||||
|
||||
### `ompgsql`
|
||||
- Depends on: `libpq` via `pg_config`
|
||||
|
||||
- Depends on: `libpq` via `pg_config`
|
||||
|
||||
### `omsnmp`
|
||||
- Depends on: `net-snmp`
|
||||
|
||||
- Depends on: `net-snmp`
|
||||
|
||||
### `omgssapi`
|
||||
- Depends on: `gssapi` library
|
||||
|
||||
---
|
||||
- Depends on: `gssapi` library
|
||||
|
||||
-----
|
||||
|
||||
## AI-Specific Hints
|
||||
|
||||
- The `modules/` directory contains dynamically loaded input/output plugins
|
||||
- `contrib/` contains external contributions (e.g., plugins) that are not core-maintained
|
||||
- `statsobj.c` implements the statistics interface
|
||||
- Documentation resides in the monorepo’s doc/ directory
|
||||
- You may reference `rsyslog-docker` for dev/test environment setup
|
||||
- Side libraries are external GitHub repos, not subdirectories
|
||||
- The `modules/` directory contains dynamically loaded input/output plugins
|
||||
|
||||
- **Shell Script Documentation**
|
||||
Use shdoc-style comments (`##`, `###`) in new and updated Bash scripts to enable automatic Markdown extraction. Many existing scripts lack these; it's **strongly recommended** to add them when modifying or creating scripts.
|
||||
- `contrib/` contains external contributions (e.g., plugins) that are not core-maintained
|
||||
|
||||
- **Final Style Check**
|
||||
Always run `python3 devtools/rsyslog_stylecheck.py` before committing. Fix any style errors and re-run until it passes.
|
||||
- `statsobj.c` implements the statistics interface
|
||||
|
||||
- Documentation resides in the monorepo’s doc/ directory
|
||||
|
||||
- You may reference `rsyslog-docker` for dev/test environment setup
|
||||
|
||||
- Side libraries are external GitHub repos, not subdirectories
|
||||
|
||||
- **Shell Script Documentation**
|
||||
Use shdoc-style comments (`##`, `###`) in new and updated Bash scripts to enable automatic Markdown extraction. Many existing scripts lack these; it's **strongly recommended** to add them when modifying or creating scripts.
|
||||
|
||||
- **Final Style Check**
|
||||
Always run `python3 devtools/rsyslog_stylecheck.py` before committing. Fix any style errors and re-run until it passes.
|
||||
|
||||
When generating or editing code, prefer:
|
||||
- Clean modular design
|
||||
- Compatibility and backward safety
|
||||
- Updating structured comments (e.g., Doxygen for C code)
|
||||
|
||||
---
|
||||
- Clean modular design
|
||||
- Compatibility and backward safety
|
||||
- Updating structured comments (e.g., Doxygen for C code)
|
||||
|
||||
-----
|
||||
|
||||
## AI Agent Commit Convention
|
||||
|
||||
If you are an AI agent contributing code or documentation:
|
||||
|
||||
- Use the same rich commit message text as your PR description.
|
||||
- Avoid generating multiple PRs for retries — reuse and update the original PR when possible.
|
||||
- Follow the same **commit message policy** as human contributors:
|
||||
- Describe **what changed** and **why** (as far as known to the agent).
|
||||
- Note any impact on existing versions or behaviors (especially for bug fixes).
|
||||
- Commit message descriptions should clearly identify that they were generated or co-authored by an AI tool.
|
||||
- Include a **commit footer tag** like "AI-Agent: Codex"
|
||||
- Use the same rich commit message text as your PR description.
|
||||
- Avoid generating multiple PRs for retries — reuse and update the original PR when possible.
|
||||
- Follow the same **commit message policy** as human contributors:
|
||||
- Describe **what changed** and **why** (as far as known to the agent).
|
||||
- Note any impact on existing versions or behaviors (especially for bug fixes).
|
||||
- Commit message descriptions should clearly identify that they were generated or co-authored by an AI tool.
|
||||
- Include a **commit footer tag** like "AI-Agent: Codex"
|
||||
|
||||
---
|
||||
-----
|
||||
|
||||
## Privacy, Trust & Permissions
|
||||
|
||||
- AI agents **must not** push changes directly to user forks — always open PRs against `rsyslog/rsyslog`
|
||||
- Do not install third-party dependencies unless explicitly approved
|
||||
- PRs must pass standard CI and review checks
|
||||
- All code **must be reviewed manually**; AI output is subject to full review
|
||||
- AI agents **must not** push changes directly to user forks — always open PRs against `rsyslog/rsyslog`
|
||||
- Do not install third-party dependencies unless explicitly approved
|
||||
- PRs must pass standard CI and review checks
|
||||
- All code **must be reviewed manually**; AI output is subject to full review
|
||||
|
||||
@ -16,11 +16,11 @@ These components are critical for understanding a module's architecture and publ
|
||||
* **Public API Functions**: Any function declared in a header file (`.h`) that is intended for use by other modules must be fully documented.
|
||||
* **Public Data Structures**: All structs, enums, and typedefs exposed in header files must be documented. This includes a description of the structure's purpose and a brief explanation for each member.
|
||||
* **Complex Functions**: Any function, public or static, whose implementation is non-trivial. Indicators of complexity include:
|
||||
* Complex algorithms or logic.
|
||||
* Subtle or non-obvious side-effects.
|
||||
* Interaction with multiple other components or systems.
|
||||
* Performance-critical code where specific implementation choices were made for optimization.
|
||||
* A large number of parameters, where the purpose of each is not immediately obvious from its name.
|
||||
* Complex algorithms or logic.
|
||||
* Subtle or non-obvious side-effects.
|
||||
* Interaction with multiple other components or systems.
|
||||
* Performance-critical code where specific implementation choices were made for optimization.
|
||||
* A large number of parameters, where the purpose of each is not immediately obvious from its name.
|
||||
|
||||
## 2. When to AVOID Doxygen Comments
|
||||
|
||||
@ -42,6 +42,25 @@ Before skipping a Doxygen comment on a function, ask these questions. If the ans
|
||||
* Are the **purpose and type of all parameters clear from their names**?
|
||||
* Does it have **no non-obvious side effects**?
|
||||
|
||||
## 4. Commenting Preprocessor Macros
|
||||
|
||||
Preprocessor macros should be documented using C-style block comments
|
||||
placed immediately above the `#define`, with Doxygen `@brief` tags.
|
||||
Inline comments on the same line as the macro may interfere with automated
|
||||
formatting (clang-format + devtools/format-code.sh) and should be moved
|
||||
into these comment blocks.
|
||||
|
||||
Example:
|
||||
```c
|
||||
/**
|
||||
* @brief Maximum size for a syslog TAG field.
|
||||
*
|
||||
* This value is intentionally set far above any realistic tag length to
|
||||
* guard against malformed or excessive configurations.
|
||||
*/
|
||||
#define CONF_TAG_MAXSIZE 512
|
||||
```
|
||||
|
||||
## Proposed Workflow for Transformation
|
||||
|
||||
1. **Prioritize the Public Interface**: First, ensure all `.h` files and their corresponding public functions and structs in `.c` files are fully documented.
|
||||
@ -49,4 +68,3 @@ Before skipping a Doxygen comment on a function, ask these questions. If the ans
|
||||
3. **Actively Skip Simple Functions**: Consciously apply the "Obvious Function" test and skip adding Doxygen blocks to trivial, static helper functions. If a function seems to need a long comment to explain what it does, first consider if it can be refactored to be more clear.
|
||||
4. **Review and Refine**: After a file is processed, review it to see if the balance feels right. Is it easy to grasp the purpose of the undocumented functions? If not, they may not be as "obvious" as initially thought, and a brief Doxygen comment might be warranted.
|
||||
|
||||
---
|
||||
|
||||
115
devtools/format-code.sh
Executable file
115
devtools/format-code.sh
Executable file
@ -0,0 +1,115 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# devtools/format-code.sh
|
||||
#
|
||||
# This script formats all .c and .h files in the rsyslog source tree
|
||||
# using clang-format, applying the style defined in the .clang-format file.
|
||||
# It's intended to enforce the canonical code format for the repository.
|
||||
#
|
||||
# Usage:
|
||||
# ./devtools/format-code-exec.sh [-h]
|
||||
#
|
||||
# Options:
|
||||
# -h, --help Display this help message and exit.
|
||||
#
|
||||
# Description:
|
||||
# This script performs an in-place reformatting of all C source (.c) and
|
||||
# header (.h) files within the current directory and its subdirectories.
|
||||
# It utilizes 'clang-format' and expects a '.clang-format' configuration
|
||||
# file to be present in the project root or a parent directory to define
|
||||
# the desired coding style.
|
||||
#
|
||||
# This version uses 'find -exec ... +' for efficient processing of multiple
|
||||
# files per 'clang-format' invocation. This approach is generally faster
|
||||
# and more robust for large codebases. Any clang-format errors for individual
|
||||
# files will be printed directly by clang-format to stderr. The script's
|
||||
# final exit code will reflect if the overall formatting process encountered
|
||||
# a critical error.
|
||||
#
|
||||
# Crucially, this version correctly groups the file name conditions using
|
||||
# parentheses `\( ... \)` to ensure that `clang-format` is executed for
|
||||
# both `.c` and `.h` files as intended.
|
||||
#
|
||||
# Before running, ensure 'clang-format' is installed on your system.
|
||||
# It is highly recommended to commit your current changes or create a backup
|
||||
# before executing this script, as it modifies files directly.
|
||||
#
|
||||
# Exit Codes:
|
||||
# 0: Overall formatting process completed successfully.
|
||||
# 1: 'clang-format' is not found or not executable.
|
||||
# 2: A critical error occurred during the 'find -exec' command.
|
||||
|
||||
# --- Script Start ---
|
||||
|
||||
# Set sensible defaults for shell options
|
||||
set -euo pipefail # Exit on error, unset variables, and pipefail
|
||||
|
||||
# --- Functions ---
|
||||
|
||||
# Function to display help message
|
||||
show_help() {
|
||||
grep '^# ' "$0" | cut -c 3- | sed -n '/^Usage:/,/^Exit Codes:/p'
|
||||
exit 0
|
||||
}
|
||||
|
||||
# --- Argument Parsing ---
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
-h|--help)
|
||||
show_help
|
||||
;;
|
||||
*)
|
||||
echo "Error: Unknown option '$1'" >&2
|
||||
show_help
|
||||
;;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
# --- Pre-checks ---
|
||||
|
||||
# Check if clang-format is installed and executable
|
||||
if ! command -v clang-format &> /dev/null; then
|
||||
echo "Error: 'clang-format' command not found." >&2
|
||||
echo "Please install it. On Ubuntu, you can run: sudo apt install clang-format" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for .clang-format file
|
||||
if ! find . -maxdepth 2 -name ".clang-format" -print -quit | grep -q .; then
|
||||
echo "Warning: No '.clang-format' file found in the current directory or its parent." >&2
|
||||
echo "Using clang-format's default style. It's highly recommended to create one for consistent formatting." >&2
|
||||
echo "You can generate a basic one with: clang-format -style=LLVM -dump-config > .clang-format" >&2
|
||||
echo ""
|
||||
fi
|
||||
|
||||
echo "Starting code formatting for .c and .h files using 'find -exec ... +'..."
|
||||
echo "Using clang-format -i -style=file"
|
||||
echo "This may take a moment. Any clang-format errors for individual files will be printed directly."
|
||||
echo "Note: 'clang-format' only modifies files that deviate from the specified style."
|
||||
echo ""
|
||||
|
||||
# --- Formatting Logic ---
|
||||
# Find all .c and .h files recursively and execute clang-format on them.
|
||||
# The '{} +' syntax passes multiple filenames to a single clang-format invocation,
|
||||
# which is more efficient.
|
||||
# The parentheses '\( ... \)' are crucial for correctly grouping the -name conditions.
|
||||
if ! find . \( -name "*.c" -o -name "*.h" \) -exec clang-format -i -style=file {} +; then
|
||||
echo "Error: The overall code formatting process failed." >&2
|
||||
echo "Please review the output above for any specific clang-format errors." >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
# Calculate total files found for summary
|
||||
# Update this find command as well to use the correct parentheses for consistency.
|
||||
TOTAL_FILES=$(find . \( -name "*.c" -o -name "*.h" \) | wc -l)
|
||||
|
||||
echo ""
|
||||
echo "--- Formatting Summary ---"
|
||||
echo "Total .c/.h files found and processed: $TOTAL_FILES"
|
||||
echo "Code formatting completed successfully."
|
||||
echo "The number of files actually changed depends on their adherence to the style."
|
||||
echo "Please review changes using 'git diff' if in a Git repository."
|
||||
|
||||
# --- Script End ---
|
||||
|
||||
@ -1591,23 +1591,23 @@ static void initAll(int argc, char **argv) {
|
||||
capng_type_t type;
|
||||
} capabilities_t;
|
||||
|
||||
// clang-format off
|
||||
capabilities_t capabilities[] = {
|
||||
#define CAP_FIELD(code, type) {code, #code, 0, type}
|
||||
CAP_FIELD(CAP_BLOCK_SUSPEND, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_NET_RAW, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_CHOWN, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_LEASE, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_NET_ADMIN, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_NET_BIND_SERVICE, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_DAC_OVERRIDE, CAPNG_EFFECTIVE | CAPNG_PERMITTED | CAPNG_BOUNDING_SET),
|
||||
CAP_FIELD(CAP_SETGID, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_SETUID, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_SYS_ADMIN, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_SYS_CHROOT, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_SYS_RESOURCE, CAPNG_EFFECTIVE | CAPNG_PERMITTED),
|
||||
CAP_FIELD(CAP_SYSLOG, CAPNG_EFFECTIVE | CAPNG_PERMITTED)
|
||||
#undef CAP_FIELD
|
||||
{ CAP_BLOCK_SUSPEND, "CAP_BLOCK_SUSPEND", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_NET_RAW, "CAP_NET_RAW", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_CHOWN, "CAP_CHOWN", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_LEASE, "CAP_LEASE", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_NET_ADMIN, "CAP_NET_ADMIN", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_NET_BIND_SERVICE, "CAP_NET_BIND_SERVICE", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_DAC_OVERRIDE, "CAP_DAC_OVERRIDE", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED | CAPNG_BOUNDING_SET },
|
||||
{ CAP_SETGID, "CAP_SETGID", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_SETUID, "CAP_SETUID", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_SYS_ADMIN, "CAP_SYS_ADMIN", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_SYS_CHROOT, "CAP_SYS_CHROOT", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_SYS_RESOURCE, "CAP_SYS_RESOURCE", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED },
|
||||
{ CAP_SYSLOG, "CAP_SYSLOG", 0, CAPNG_EFFECTIVE | CAPNG_PERMITTED }
|
||||
};
|
||||
// clang-format on
|
||||
|
||||
if (capng_have_capabilities(CAPNG_SELECT_CAPS) > CAPNG_NONE) {
|
||||
/* Examine which capabilities are available to us, so we do not try to
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user