Developing Arcalibre
The rereading Project welcomes your contributions to Arcalibre, thanks for helping us make the best software possible for managing your e-book library.
Obtaining Arcalibre Source
The source code for Arcalibre is hosted on Codeberg at https://codeberg.org/rereading/arcalibre/, and can be downloaded using Git, or as zip file. We recommend using Git, as doing so makes it as easy as possible to keep your copy of Arcalibre up to date with changes, and to submit your contributions back to the rereading Project.
While using Git in detail is beyond the scope of this guide, the git clone command can be used to obtain a copy of Arcalibre:
Many of the Python packages that Arcalibre depends on are hosted separately in the https://codeberg.org/rereading/pyreading, such that they can be built and used independently of the rest of the Arcalibre project. These packages include XML support, internationalization and locale handling, PDF support, and more.
Setting Up Your Development Environment
With Nix
Arcalibre is written in Python, but depends on other components such as C/C++ and Rust compilers, PDF manipulation tools, and other system libraries. The easiest way to get your development environment up and running, including an installation of Python together with all required compilers and libraries is to use Nix on Linux or macOS. Once you have Nix installed, you can run nix-shell from within the Arcalibre repository to automatically make all requirements available without modifying your system.
Manually
TODO
Building Arcalibre
Arcalibre uses do-runner, a Makefile-style command runner, to automate building and testing. The go-do command is provided automatically as a Python development dependency for use with PDM, or can be installed manually. For the rest of this section, we will assume that the go-do command is available on your PATH, but you may need to preface the following commands by pdm run or pdm run -g depending on how you have your environment configured.
To obtain a list of build commands, known as recipes, run go-do without any arguments.
To build Arcalibre, first create the Python virtual environment for the repo:
Then, the build recipe will compile all native code used by Arcalibre, and will download translations and other resources.
After the build recipe has completed, you should be able to run Arcalibre with the run recipe:
Running Tests
To run unit and integration tests for Arcalibre:
Specific tests can be selected using pytest command options. For example, to run only the tests in test_import.py, use the -k flag:
To run type checking, linting, and formatting checks:
Updating Python Dependencies
The pyproject.toml file lists all Python dependencies needed by Arcalibre. If you make changes to these dependencies, you will need to regenerate the lock files used to ensure that builds are reproducible, then update your virtual environment with these new dependencies:
This will result in the pdm.lock file being re-created, please be sure to include these changes in your contributions.
Checking CI
Finally, before pushing to Codeberg, you can check the CI pipeline locally by using the ci task:
This will not replicate CI features such as cross-platform builds or isolating builds in Docker containers, but can help find minor issues without needing to wait for CI.