devs/cproof
1
2
Fork 1
Code Issues 43 Pull Requests 6 Actions Packages Projects 1 Releases Wiki Activity

docs: Expand the build section in CONTRIBUTING.md

Browse Source 
Usually we point to the website. But honestly it's cumbersome for
developers to update the website. Let's decide later whether we remove
the section there or how we keep it in sync.

But for now let's just add a detailed build section here.
Especially since now we ship autotools *and* meson.

Also mention the convention that we use `build_run` as the meson build
dir. The quality script will depend on this.
This commit is contained in:
Michael Vetter
2026-02-28 14:15:17 +01:00
parent 91911b3e2f
commit aadf912e0e
1 changed files with 45 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
CONTRIBUTING.md
View File

@@ -1,8 +1,42 @@
# Contributing to Profanity
## Build
Profanity can be built using either **Autotools** or **Meson**.
Please follow the [build section](https://profanity-im.github.io/guide/latest/build.html) in our user guide.
### Build Options
Both build systems support several features that can be enabled or disabled.
**Important Difference:**
- **Autotools**: Features are **auto-enabled** if the required dependencies are found on your system during the `./configure` step.
- **Meson**: Features must be **explicitly enabled**. Nothing is auto-enabled; if you want a feature, you must pass the corresponding `-Doption=enabled` flag.
| Feature | Description | Autotools flag | Meson option |
| :--- | :--- | :--- | :--- |
| **Notifications** | Desktop notifications support | `--enable-notifications` | `-Dnotifications=enabled` |
| **Python Plugins** | Support for Python plugins | `--enable-python-plugins` | `-Dpython-plugins=enabled` |
| **C Plugins** | Support for C plugins | `--enable-c-plugins` | `-Dc-plugins=enabled` |
| **OTR** | Off-the-Record encryption | `--enable-otr` | `-Dotr=enabled` |
| **PGP** | PGP encryption support | `--enable-pgp` | `-Dpgp=enabled` |
| **OMEMO** | OMEMO encryption support | `--enable-omemo` | `-Domemo=enabled` |
| **QR Code** | OMEMO QR code display | `--enable-omemo-qrcode` | `-Domemo-qrcode=enabled` |
| **Icons/Clipboard** | GTK tray icons & clipboard | `--enable-icons-and-clipboard` | `-Dicons-and-clipboard=enabled` |
| **GDK Pixbuf** | Avatar scaling support | `--enable-gdk-pixbuf` | `-Dgdk-pixbuf=enabled` |
| **XScreenSaver** | Idle time detection | `--with-xscreensaver` | `-Dxscreensaver=enabled` |
| **Tests** | Build unit tests | *Built by default* | `-Dtests=true` |
| **Sanitizers** | Run-time error detection | *Via CFLAGS* | `-Db_sanitize=address,undefined` |
### Using Autotools
1. Generate configuration files: `./bootstrap.sh`
2. Configure: `./configure --enable-otr --enable-omemo`
3. Build: `make`
4. Run: `./profanity`
### Using Meson
1. Setup build directory: `meson setup build_run -Domemo=enabled -Dotr=enabled`
2. Build: `meson compile -C build_run`
3. Run: `./build_run/profanity`
We also have a [build section](https://profanity-im.github.io/guide/latest/build.html) in our user guide.
You might also take a look at the `Dockerfile.*` in the root directory.
## Submitting patches
@@ -41,8 +75,9 @@ Then our team can easily request reviews. And we have the history of the review
If using GitHub is out of the question but you are okay using another service (i.e.: GitLab, codeberg) then please message us in the MUC or send us an email.
We will then pull from your repository and merge manually.
### Rules
## Rules & Guidelines
### Contribution Rules
* When fixing a bug, describe it and how your patch fixes it.
* When fixing a reported issue add an `Fixes https://github.com/profanity-im/profanity/issues/23` in the commit body.
* When adding a new feature add a description of the feature and how it should be used (workflow).
@@ -54,12 +89,12 @@ We will then pull from your repository and merge manually.
* Squash fixup commits into one
* If applicable, document how to test the functionality
## Hints and Pitfalls
### Hints and Pitfalls
* When adding a new hotkey/shortcut make sure it's not registered in Profanity already. And also that it's not a default shortcut of readline.
* We ship a `.git-blame-ignore-revs` file containing banal commits which you will most likely want to ignore when using `git blame`. In case you are using vim and [fugitive](https://github.com/tpope/vim-fugitive) `command Gblame Git blame --ignore-revs-file=.git-blame-ignore-revs` might be helpful in your vimrc. You can also set the `blame.ignoreRevsFile` option in your git config to have `git blame` generally ignore the listed commits.
## Coding style
## Coding Style
Follow the style already present ;-)
To make this easier for you we created a `.clang-format` file.
@@ -105,15 +140,12 @@ In cases where you want to disable automatic formatting for a specific block of
/* clang-format on */
```
## Finding mistakes
Test your changes with the following tools to find mistakes.
### Unit tests
## Verification & Testing
### Running unit tests
Run `make check` to run the unit tests with your current configuration or `./ci-build.sh` to check with different switches passed to configure.
### Writing unit tests
We use the [cmocka](https://cmocka.org/) testing framework for unit tests.
Test files are located in `tests/unittests` and should mirror the directory structure of the `src/` directory. For example, if you are testing `src/xmpp/jid.c`, the corresponding test file should be `tests/unittests/xmpp/test_jid.c`.
@@ -139,7 +171,7 @@ When adding a new test file:
2. Register the test functions in `tests/unittests/unittests.c` within the `all_tests` array.
3. Add the new source file to `unittest_sources` in both `meson.build` and `Makefile.am`.
### valgrind
### Valgrind
We provide a suppressions file `prof.supp`. It is a combination of the suppressions for shipped with glib2, python and custom rules.
`G_DEBUG=gc-friendly G_SLICE=always-malloc valgrind --tool=memcheck --track-origins=yes --leak-check=full --leak-resolution=high --num-callers=30 --show-leak-kinds=definite --log-file=profval --suppressions=prof.supp ./profanity`
@@ -150,8 +182,7 @@ There's also the option to create a "personalized" suppression file with the up-
After executing this, you can replace the `--suppressions=prof.supp` argument in the above call, by `--suppressions=my-prof.supp`.
### clang
### Clang Static Analyzer
Running the clang static code analyzer helps improving the quality too.
```
@@ -161,7 +192,6 @@ scan-view ...
```
### Finding typos
We include a `.codespellrc` configuration file for `codespell` in the root directory.
Before committing it might make sense to run `codespell` to see if you made any typos.
@@ -179,6 +209,7 @@ If using Meson:
```
meson compile doublecheck
```
*Note: The script expects the build directory to be named `build_run` as specified in the Meson build instructions above.*
Alternatively, you can run the script directly:
```
@@ -197,4 +228,3 @@ If you need to bypass the formatting check (e.g. due to a `clang-format` version
```
SKIP_FORMAT=1 git commit
```