ceos/cagebreak
1
0
Fork 0
mirror of https://cagebreak.project-repo.co/cagebreak.git synced 2026-08-09 15:19:11 +02:00
Code Issues Projects Releases Packages Wiki Activity

Fix README copy error

Browse source
This commit is contained in:
Cagebreak Signing Key 7 2021-12-31 12:55:13 +01:00
commit 296b106d44
1 changed files with 3 additions and 362 deletions
Download patch file Download diff file Expand all files Collapse all files

365
README.md
View file

@ -308,28 +308,13 @@ In the meantime, add `-Db_detect-leaks=0` to the meson command to exclude memory
For any bug, please [create an
issue](https://github.com/project-repo/cagebreak/issues/new) on
[GitHub](https://github.com/project-rep/cagebreak).
[GitHub](https://github.com/project-repo/cagebreak).
Fixed bugs are to be assigned a number and summarized inside Bugs.md for future reference
independent of github, in case this service is unavailable.
### Security Bugs
Should you want to get in touch with the developers of cagebreak to report a
security vulnerability or a different issue confidentially, contact
`cagebreak @ project-repo . co`.
We will try to respond to everything that is not obvious spam.
Please encrypt your email with the appropriate GPG key found in `keys/`.
* B15B92642760E11FE002DE168708D42451A94AB5
* F8DD9F8DD12B85A28F5827C4678E34D2E753AA3C
Note that the keys are signed by cagebreak signing keys.
If you want us to respond via GPG-encrypted mail, please include your own
public key or provide the fingerprint and directions to obtain the key.
For other means of contacting the Cagebreak authors and for security issues
see [SECURITY.md](SECURITY.md).
## Changelog
@ -345,347 +330,3 @@ See [Changelog.md](Changelog.md)
Please see [LICENSE](https://github.com/project-repo/cagebreak/blob/master/LICENSE# Cagebreak: A Wayland Tiling Compositor Inspired by Ratpoison
This is Cagebreak, a Wayland tiling compositor. The goal of this project is to
provide a successor to ratpoison for Wayland users. However, this is
no reimplementation of ratpoison. Should you like to know if a feature
will be implemented, open an issue or get in touch with the development team.
For documentation of Cagebreak, please see
the man pages for [cagebreak](man/cagebreak.1.md) and cagebreak
[configuration](man/cagebreak-config.5.md) and the
[Wiki](https://github.com/project-repo/cagebreak/wiki/).
Cagebreak is based on [Cage](https://github.com/Hjdskes/cage), a Wayland kiosk
compositor.
Cagebreak is currently being developed under Arch Linux and uses the libraries
as they are obtained through pacman. However, cagebreak should also work on
other distributions given the proper library versions.
## Installation
If you are using archlinux, just use the PKGBUILDs from the aur:
* Using the `cagebreak` package, Cagebreak is compiled on the target system (since release 1.3.0)
* Using `cagebreak-bin` package, the pre-built binaries are extracted to the appropriate paths on the target system (since release 1.3.2)
See [cagebreak-pkgbuild](https://github.com/project-repo/cagebreak-pkgbuild) for details.
### Obtaining Source Code
There are different ways to obtain cagebreak source:
* git clone (for all releases)
* download release asset tarballs (starting at release 1.2.1)
### Verifying Source Code
There are corresponding methods of verifying that you obtained the correct code:
* our git history includes signed tags for releases
* release assets starting at release 1.2.1 contain a signature for the tarball
### Building Cagebreak
You can build Cagebreak with the [meson](https://mesonbuild.com/) build system. It
requires wayland, wlroots and xkbcommon to be installed. Note that Cagebreak is
developed against the latest tag of wlroots, in order not to constantly chase
breaking changes as soon as they occur.
Simply execute the following steps to build Cagebreak:
```
$ meson build
$ ninja -C build
```
#### Release Build
By default, this builds a debug build. To build a release build, use `meson
build --buildtype=release`.
#### Xwayland Support
Cagebreak comes with compile-time support for XWayland. To enable this,
first make sure that your version of wlroots is compiled with this
option. Then, add `-Dxwayland=true` to the `meson` command above. Note
that you'll need to have the XWayland binary installed on your system
for this to work.
#### Man Pages
Cagebreak has man pages. To use them, make sure that you have `pandoc`
installed. Then, add `-Dman-pages=true` to the `meson` command.
### Running Cagebreak
You can start Cagebreak by running `./build/cagebreak`. If you run it from
within an existing X11 or Wayland session, it will open in a virtual output as
a window in your existing session. If you run it in a TTY, it'll run with the
KMS+DRM backend. For more configuration options, see the man pages.
## Contributing to Cagebreak
Cagebreak is currently developed to fit the needs of its creators. Should you desire
to implement a feature, please let us know in advance by opening an issue. However,
the feature set is intentionally limited (i.e. we removed support for a desktop
background) and will continue to be so in the future.
Nonetheless, don't be intimidated by the (slightly lengthy) release checklist or any other
part of this file. Do what you can, open an issue and we will collaborate
toward a solution.
### Branching Strategy and Versioning
All features are to be developed on feature branches, named after the feature.
There exists a branch `development` to which all reasonable feature branches
are merged for final testing.
Once `development` is ready for a release, meaning that the release checklist is fulfilled,
it is merged into `master`, creating a new release, which is tagged and signed.
All releases are tagged according to [semantic versioning](https://semver.org) guidelines.
In the past, our git history did not perfectly reflect this scheme.
### Releases
The release checklist must be completely fulfilled in one run for a release to
occur. Once any failure occurs the entire checklist must be completed from scratch.
* [ ] `git checkout development`
* [ ] `git pull origin development`
* [ ] `git push origin development`
* [ ] `ninja -C build clang-format` makes no changes
* [ ] New version number determined according to [semantic versioning](https://semver.org) guidelines
* [ ] Relevant Documentation completed
* [ ] New features
* [ ] man pages
* [ ] man/cagebreak
* [ ] man/cagebreak-config
* [ ] Set EPOCH to release day in man generation in meson.build
* [ ] wiki
* [ ] Changelog.md for major and minor releases but not patches
* [ ] Fixed bugs documented in Bugs.md
* [ ] Include issue description from github
* [ ] Testing
* [ ] Manual testing
* [ ] Libfuzzer testing
* [ ] Version Number
* [ ] meson.build
* [ ] git tag
* [ ] man pages
* [ ] meson.build reproducible build versions are current archlinux libraries and gcc
* [ ] Cagebreak is reproducible on multiple machines
* [ ] Documented reproducible build artefacts
* [ ] Hashes of the artefacts in Hashes.md
* [ ] Renamed previous signatures
* [ ] Created gpg signature of the artefacts
* [ ] `gpg --detach-sign -u keyid cagebreak`
* [ ] `gpg --detach-sign -u keyid cagebreak.1`
* [ ] `gpg --detach-sign -u keyid cagebreak-config.5`
* [ ] `git add` relevant files
* [ ] `git commit`
* [ ] `git push origin development`
* [ ] Determined commit and tag message (Start with "Release version_number\n\n")
* [ ] Mentioned fixed Bugs.md issues ("Fixed Issue n")
* [ ] Mentioned other important changes
* [ ] `git checkout master`
* [ ] `git merge --squash development`
* [ ] `git commit` and insert message
* [ ] `git tag -u keyid version HEAD` and insert message
* [ ] `git tag -v version` and check output
* [ ] `git push --tags origin master`
* [ ] `git checkout development`
* [ ] `git merge master`
* [ ] `git push --tags origin development`
* [ ] `git archive --prefix=cagebreak/ -o release_version.tar.gz tags/version .`
* [ ] Create release-artefacts_version.tar.gz
* [ ] `mkdir release-artefacts_version`
* [ ] `cp build/cagebreak release-artefacts_version/`
* [ ] `cp build/cagebreak.sig release-artefacts_version/`
* [ ] `cp build/cagebreak.1 release-artefacts_version/`
* [ ] `cp build/cagebreak.1.sig release-artefacts_version/`
* [ ] `cp build/cagebreak-config.5 release-artefacts_version/`
* [ ] `cp build/cagebreak-config.5.sig release-artefacts_version/`
* [ ] `cp LICENSE release-artefacts_version/`
* [ ] `export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) ; tar --sort=name --mtime= --owner=0 --group=0 --numeric-owner -czf release-artefacts_version.tar.gz release-artefacts_version`
* [ ] Checked archive
* [ ] tar -xvf release_version.tar.gz
* [ ] cd cagebreak
* [ ] meson build -Dxwayland=true -Dman-pages=true --buildtype=release
* [ ] ninja -C build
* [ ] gpg --verify ../signatures/cagebreak.sig build/cagebreak
* [ ] cd ..
* [ ] rm -rf cagebreak
* [ ] `gpg --detach-sign -u keyid release_version.tar.gz`
* [ ] `gpg --detach-sign -u keyid release-artefacts_version.tar.gz`
* [ ] Upload archives and signatures as release assets
### Reproducible Builds
Cagebreak offers reproducible builds given the exact library versions specified
in `meson.build`. Should a version mismatch occur, a warning will be emitted. We have
decided on this compromise to allow flexibility and security. In general we will
adapt the versions to the packages available under Arch Linux at the time of
release.
There are reproducibility issues up to and including release `1.2.0`. See
`Issue 5` in [Bugs.md](Bugs.md).
#### Reproducible Build Instructions
All hashes and signatures are provided for the following build instructions.
```
meson build -Dxwayland=true -Dman-pages=true --buildtype=release
ninja -C build
```
#### Hashes for Builds
For every release after 1.0.5, hashes will be provided.
For every release after 1.7.0, hashes will be provided for man pages too.
See [Hashes.md](Hashes.md)
#### GPG Signatures
For every release after 1.0.5, a GPG signature will be provided in `signatures`.
The current signature is called `cagebreak.sig`, whereas all older signatures
will be named after their release version.
Due to errors in the release process, the releases 1.7.1 and 1.7.2 did not include the release
signatures in the appropriate folder of the git repository. However, signatures were provided
as release-artefacts at the time of release. The signatures were introduced into the
repository with 1.7.3. The integrity of cagebreak is still the same because the signatures were
provided as release-artefacts (which were themselves signed) and the hashes in Hashes.md
are part of a signed release tag.
#### Signing Keys
All releases are signed by at least one of the following collection of
keys.
* E79F6D9E113529F4B1FFE4D5C4F974D70CEC2C5B
* 4739D329C9187A1C2795C20A02ABFDEC3A40545F
* 7535AB89220A5C15A728B75F74104CC7DCA5D7A8
* 827BC2320D535AEAD0540E6E2E66F65D99761A6F
* A88D7431E5BAAD0B6EAE550AC8D61D8BD4FA3C46
* 8F872885968EB8C589A32E9539ACC012896D450F
* 896B92AF738C974E0065BF42F2576BD366156BB9
* AA927AFD50AF7C6810E69FE8274F2C605359E31B
Should we at any point retire a key, we will only replace it with keys signed
by at least one of the above collection.
We registered project-repo.co and added mail addresses after release `1.3.0`.
We now have a mail address and its key is signed by signing keys. See Security
Bugs for details.
The full public keys can be found in `keys/` along with any revocation certificates.
### GCC and -fanalyzer
Cagebreak should compile with any reasonably new gcc or clang. Consider
a gcc version of at least [10.1](https://gcc.gnu.org/gcc-10/changes.html) if
you want to get the benefit of the brand-new
[-fanalyzer](https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html)
flag. However, this new flag sometimes produces false-postives and we
selectively disable warnings for affected code segments as described below.
Meson is configured to set `CG_HAS_FANALYZE` if `-fanalyzer` is available.
Therefore, to maintain portability, false-positive fanalyzer warnings are to be
disabled using the following syntax:
```
#if CG_HAS_FANALYZE
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "WARNING OPTION"
#endif
```
and after
```
#if CG_HAS_FANALYZE
#pragma GCC diagnostic pop
#endif
```
### Fuzzing
Along with the project source code, a fuzzing framework based on `libfuzzer` is
supplied. This allows for the testing of the parsing code responsible for reading
the `cagebreak` configuration file. When `libfuzzer` is available (please
use the `clang` compiler to enable it), building the fuzz-testing software can
be enabled by passing `-Dfuzz=true` to meson. This generates a `build/fuzz/fuzz-parse`
binary according to the `libfuzzer` specifications. Further documentation on
how to run this binary can be found [here](https://llvm.org/docs/LibFuzzer.html).
Here is an example workflow:
```
rm -rf build
CC=clang meson build -Dfuzz=true -Db_sanitize=address,undefined -Db_lundef=false
ninja -C build/
mkdir build/fuzz_corpus
cp examples/config build/fuzz_corpus/
WLR_BACKENDS=headless ./build/fuzz/fuzz-parse -jobs=12 -max_len=50000 -close_fd_mask=3 build/fuzz_corpus/
```
You may want to tweak `-jobs` or add other options depending on your own setup.
We have found code path discovery to increase rapidly when the fuzzer is supplied
with an initial config file. We are working on improving our fuzzing coverage to
find bugs in other areas of the code.
#### Caveat
Currently, there are memory leaks which do not seem to stem from our code but rather
the code of wl-roots or some other library we depend on. We are working on the problem.
In the meantime, add `-Db_detect-leaks=0` to the meson command to exclude memory leaks.
## Bugs
For any bug, please [create an
issue](https://github.com/project-repo/cagebreak/issues/new) on
[GitHub](https://github.com/project-rep/cagebreak).
Fixed bugs are to be assigned a number and summarized inside Bugs.md for future reference
independent of github, in case this service is unavailable.
### Security Bugs
Should you want to get in touch with the developers of cagebreak to report a
security vulnerability or a different issue confidentially, contact
`cagebreak @ project-repo . co`.
We will try to respond to everything that is not obvious spam.
Please encrypt your email with the appropriate GPG key found in `keys/`.
* B15B92642760E11FE002DE168708D42451A94AB5
* F8DD9F8DD12B85A28F5827C4678E34D2E753AA3C
Note that the keys are signed by cagebreak signing keys.
If you want us to respond via GPG-encrypted mail, please include your own
public key or provide the fingerprint and directions to obtain the key.
## Changelog
See [Changelog.md](Changelog.md)
## Contributors
* Aisha Tammy
* [make man pages optional](https://github.com/project-repo/cagebreak/pull/4), released
in 1.6.0 with slight modifications
## License
Please see [LICENSE](https://github.com/project-repo/cagebreak/blob/master/LICENSE))