diff --git a/README.md b/README.md index d02364a..bf65f82 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,10 @@ debmagic logo Debmagic is for [Debian](https://debian.org)/[Ubuntu](https://ubuntu.com): + - create packages **build instructions** in Python with `debian/rules.py` - tooling do perform packaging itself: **building** and **testing** in isolated container environments - [![GitHub Actions Status](https://github.com/SFTtech/debmagic/actions/workflows/ci.yml/badge.svg)](https://github.com/SFTtech/debmagic/actions/workflows/ci.yml) > [!IMPORTANT] @@ -21,7 +21,6 @@ Included features: - maintainer tools - `debmagic build` - isolated package building - ## Example debian/rules.py Python `debian/rules.py` equivalent of [Ubuntu 24.04 htop](https://git.launchpad.net/ubuntu/+source/htop/tree/debian/rules?h=ubuntu/noble): @@ -82,7 +81,7 @@ pkg.pack() To add custom functions directly usable from CLI (like custom `debian/rules` targets for maintainers): -``` python +```python pkg = package(...) @pkg.custom_function @@ -94,54 +93,30 @@ pkg.pack() This function can be directly called with: -``` console +```console ./debian/rules.py something-custom --another-param=test 1337 ``` -``` text + +```text you passed some_param=test another_param=1337 ``` And generates automatic help for: -``` console -./debian/rules.py something-custom --help -``` - - -## Developing - -Prerequisites: -- Debian >= trixie, either roll your own environment or to get started faster use the [devcontainer](https://containers.dev/) -- Python >= 3.12 -- [UV](https://docs.astral.sh/uv/) - -Setup: - -```bash -uv sync -uv run pre-commit install -``` - -Build the documentation - -```bash -# oneshot build -uv run sphinx-build docs docs/_build -# continous serving -uv run sphinx-autobuild docs docs/_build +```console +./debian/rules.py something-custom --help ``` - ## Documentation To do packaging with debmagic, please **[read the documentation!](https://debmagic.readthedocs.io)**. - ## Contributing Debmagic can always use more features and modules! You can also just request features or report bugs - this project is happy about your contributions! +- [Contributor documentation](https://debmagic.readthedocs.io/en/latest/develop/index.html) - [Issue tracker](https://github.com/SFTtech/debmagic/issues) - [Code contributions](https://github.com/SFTtech/debmagic/pulls) - [Development roadmap](https://github.com/SFTtech/debmagic/projects) @@ -152,12 +127,11 @@ To directly reach developers and other users, we have chat rooms. For questions, suggestions, problem support, please join and just ask! | Contact | Where? | -|---------------|------------------------------------------------------------------------------------------------| +| ------------- | ---------------------------------------------------------------------------------------------- | | Issue Tracker | [SFTtech/debmagic](https://github.com/SFTtech/debmagic/issues) | | Matrix Chat | [`#sfttech:matrix.org`](https://app.element.io/#/room/#sfttech:matrix.org) | | Support us | [![donations](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/SFTtech) | - ## License Released under the **GNU General Public License** version 2 or later, [LICENSE](legal/GPL-2) for details. diff --git a/docs/conf.py b/docs/conf.py index 76cf58a..b002e1d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,6 +20,8 @@ ] myst_enable_extensions = [ "colon_fence", + "html_image", + "attrs_inline", ] templates_path = ["_templates"] diff --git a/docs/develop/index.md b/docs/develop/index.md index 5f2beb9..3bc9d42 100644 --- a/docs/develop/index.md +++ b/docs/develop/index.md @@ -3,5 +3,30 @@ This section covers documentation relevant to developing and maintaining the debmagic codebase, and some guidelines for how you can contribute. +## Getting started with development + +Prerequisites: + +- Debian >= trixie, either roll your own environment or to get started faster use the [devcontainer](https://containers.dev/) +- Python >= 3.12 +- [UV](https://docs.astral.sh/uv/) + +Setup: + +```shell +uv sync +uv run pre-commit install +``` + +Build the documentation + +```shell +# oneshot build +uv run sphinx-build docs docs/_build +# continous serving +uv run sphinx-autobuild docs docs/_build +``` + ```{toctree} -``` \ No newline at end of file + +``` diff --git a/docs/index.md b/docs/index.md index 123a0d8..4a447f1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,13 @@ # debmagic +![debmagic image](../assets/debmagic-logo.svg){width=250px align=center} + ```{toctree} :hidden: :caption: Usage usage/getting-started.md -usage/installation.md +usage/modules/index.md ``` ```{toctree} @@ -20,4 +22,4 @@ develop/index.md :caption: 📖 Reference develop/_changelog.md -``` \ No newline at end of file +``` diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.md index 31dd91e..517dc5a 100644 --- a/docs/usage/getting-started.md +++ b/docs/usage/getting-started.md @@ -1,2 +1,107 @@ # Getting Started +## Installation + +### Pip + +```shell +pip install debmagic +``` + +or directly use uv + +```shell +uvx debmagic +``` + +### Debian / Ubuntu - Soon (tm) + +```shell +apt install debmagic +``` + +## Example debian/rules.py + +Python `debian/rules.py` equivalent of [Ubuntu 24.04 htop](https://git.launchpad.net/ubuntu/+source/htop/tree/debian/rules?h=ubuntu/noble): + +```python +#!/usr/bin/env python3 + +from debmagic.v0 import Build, autotools, dh, package + +pkg = package( + preset=[dh], + maint_options="hardening=+all", +) + +if pkg.buildflags.DEB_HOST_ARCH_OS == "linux": + configure_params = ["--enable-affinity", "--enable-delayacct"] +else: + configure_params = ["--enable-hwloc"] + +# hurd-i386 can open /proc (nothing there) and /proc/ which works +if pkg.buildflags.DEB_HOST_ARCH_OS == "hurd": + configure_params += ["--with-proc=/proc/"] +else: + configure_params += ["--enable-sensors"] + + +@pkg.stage +def configure(build: Build): + autotools.configure( + build, + ["--enable-openvz", "--enable-vserver", "--enable-unicode", *configure_params], + ) + +pkg.pack() +``` + +### debhelper compatibility + +Debmagic can use `dh` and provides **dh overrides** as common in `debian/rules` Makefiles: + +```python +from debmagic.v0 import dh + +# specify dh arguments: +dhp = dh.Preset("--with=python3 --builddirectory=build") +pkg = package(preset=dhp) + +# define optional overrides: +@dhp.override +def dh_auto_install(build: Build): + print("dh override worked :)") + build.cmd("dh_auto_install --max-parallel=1") + +pkg.pack() +``` + +### Custom functions + +To add custom functions directly usable from CLI (like custom `debian/rules` targets for maintainers): + +```python +pkg = package(...) + +@pkg.custom_function +def something_custom(some_param: int, another_param: str = "some default"): + print(f"you passed {some_param=} {another_param=}") + +pkg.pack() +``` + +This function can be directly called with: + +```console +./debian/rules.py something-custom --another-param=test 1337 +``` + +```text +you passed some_param=test another_param=1337 +``` + +And generates automatic help for: + +```console +./debian/rules.py something-custom --help +``` diff --git a/docs/usage/installation.md b/docs/usage/installation.md deleted file mode 100644 index 25267fe..0000000 --- a/docs/usage/installation.md +++ /dev/null @@ -1 +0,0 @@ -# Installation diff --git a/docs/usage/modules/autotools.md b/docs/usage/modules/autotools.md new file mode 100644 index 0000000..14aa371 --- /dev/null +++ b/docs/usage/modules/autotools.md @@ -0,0 +1 @@ +# Autotools diff --git a/docs/usage/modules/dh.md b/docs/usage/modules/dh.md new file mode 100644 index 0000000..bc24916 --- /dev/null +++ b/docs/usage/modules/dh.md @@ -0,0 +1 @@ +# Debhelper Compatibility diff --git a/docs/usage/modules/index.md b/docs/usage/modules/index.md new file mode 100644 index 0000000..7ee9d3e --- /dev/null +++ b/docs/usage/modules/index.md @@ -0,0 +1,9 @@ +# Modules + +```{toctree} +:hidden: +:caption: Modules + +autotools.md +dh.md +```