diff --git a/src/content/docs/getting-started/building.md b/src/content/docs/getting-started/building.md index b58d78d..134a58c 100644 --- a/src/content/docs/getting-started/building.md +++ b/src/content/docs/getting-started/building.md @@ -3,127 +3,119 @@ title: Building description: A console-based XMPP client for power users. sidebar: order: 2 +tableOfContents: + maxHeadingLevel: 4 --- -CProof is a console-based XMPP client written in C. It's built using the GNU's NCurses, libstrophe and it's ultimately based on the Profanity. +CProof is a console-based XMPP client written in C. It's built using the GNU's NCurses, libstrophe and it's based on the Profanity. -CProof uses the _Autotools_ for its build system. The _Autotools_ consist of _Autoconf_ and _Automake_. This page doesn't go in any detail about the _Autotools_, but describes the commands needed to build CProof, and brief descriptions of the various stages. You will also need _autoconf-archive_. +CProof uses the `GNU Autotools` build system, which includes Autoconf and Automake. This guide provides the commands to build and install CProof, along with brief descriptions of each step. For detailed information about `GNU Autotools`, refer to its official documentation. -You can either download the archive from the homepage or use git, a version control system, to get the latest code. +## Obtaining the Source Code -If you want to get the latest version from git you'll have to do: +You can obtain the CProof source code in one of two ways: + +1. **Download the archive**: Get the latest snapshot from the [CProof repository archive](https://git.jabber.space/devs/cproof/archive/master.zip) and extract it. +2. **Clone the repository**: To get the latest development version, run: ```bash -git clone https://git.jabber.space/devs/profanity.git +git clone https://git.jabber.space/devs/cproof.git ``` -After obtaining the source code, and extracting it, use the following commands to build and install +To navigate inside of the download folder, you can use `cd` command, for example: +```bash +cd cproof +``` + +After obtaining the source code, use the following commands to build and install ```bash ./bootstrap.sh ./configure make -make install +sudo make install ``` -The first step is only needed if you pulled from git +Various dependencies are required to install CProof, the `./configure` script will fail if the minimum dependencies cannot be found. -The final step requires root privileges. - -Various dependencies are required to install CProof, the _./configure_ script will fail if the minimum dependencies cannot be found. - -The latest code in _master_ is also kept up to date with development changes to libstrophe, so a manual build of this library may also be needed +The latest code in`master` is also kept up to date with development changes to libstrophe, so a manual build of this library may also be needed ## Dependencies -The package names below are from Ubuntu and may differ per distribution. +CProof requires specific dependencies for building and running. The `./configure` script checks for these and fails if any are missing. Package names vary by distribution; the following are based on Ubuntu. Refer to your distribution’s package manager for equivalents. -### Build dependencies +### Build Dependencies +- `automake`: Generates `Makefile` from `Makefile.am`. +- `autoconf`: Processes `configure.ac` to create the `configure` script. +- `autoconf-archive`: Provides additional macros for configuration. +- `libtool`: Manages shared libraries during the build. +- `pkg-config`: Resolves library paths and versions. -```plaintext -automake -autoconf -autoconf-archive -libtool -pkg-config -``` +### Required Runtime Dependencies +- `libstrophe`: XMPP library; the `master` branch requires the latest development version, which may need to be built manually. See the [libstrophe GitHub repository](https://github.com/strophe/libstrophe). +- `ncurses`: Terminal interface support (development package). +- `glib`: General-purpose utility library (development package). +- `libcurl`: HTTP client support (development package). +- `readline`: Command-line editing support (development package). +- `sqlite3`: Database support for message history (development package). -### Required dependencies +### Optional Runtime Dependencies +- `libnotify`: Desktop notification support. +- `libxss`: Desktop idle time autoaway support. +- `libotr`: OTR encryption support. +- `libgpgme`: PGP encryption support. +- `libsignal-protocol-c`: OMEMO encryption support (requires `libgcrypt` >= 1.7). +- `gtk2` or `gtk3`: Desktop tray icon support. +- `python`: Python plugin support. +- `cmocka`: Required to run tests. +- `shared-mime-info`: Sends files with correct MIME types. +- `gdk-pixbuf2`: Image scaling for `/avatar set`. +- `qrencode`: Displays OMEMO QR codes. -CProof is using libstrophe. +### Installing Dependencies by Distribution +Below are commands to install dependencies for various distributions. These are community-contributed and may be outdated. To update this guide, edit it using the link at the bottom of the page. -CProof also requires development packages of: - -```plaintext -ncurses -glib -libcurl -readline -sqlite3 -``` - -### Optional dependencies - -```plaintext -libnotify # Desktop notification support -libxss # Desktop idle time autoaway support -libotr # OTR support -libgpgme # PGP support -libsignal-protocol-c # OMEMO support -libgcrypt # OMEMO support (>= 1.7) -gtk2 or gtk3 # Desktop tray icon support -python # Python plugin support -cmocka # To run tests -shared-mime-info # Send files with the correct mime type -gdk-pixbuf2 # Scale the image for `/avatar set` -qrencode # Display OMEMO QR code -``` - -## Distribution details - -To make it easier to install all the required packages in various distributions we collect copy pastes here. These are contributed to users and might be out of date. Feel free to create pull request to improve this section. - -### Debian +#### Debian ```bash -apt-get install libcaca-dev libnotify-dev libgtk2.0-dev libotr5-dev libssl-dev libstrophe-dev pkg-config python3-dev libexpat1-dev libncursesw5-dev libglib2.0-dev libreadline-dev libgpgme11-dev libcurl4-gnutls-dev uuid-dev libcmocka-dev libgcrypt20-dev libsignal-protocol-c-dev libxss-dev libsqlite3-dev autoconf-archive autoconf libgdk-pixbuf-2.0-dev libqrencode-dev +sudo apt-get install libcaca-dev libnotify-dev libgtk2.0-dev libotr5-dev libssl-dev libstrophe-dev pkg-config python3-dev libexpat1-dev libncursesw5-dev libglib2.0-dev libreadline-dev libgpgme11-dev libcurl4-gnutls-dev uuid-dev libcmocka-dev libgcrypt20-dev libsignal-protocol-c-dev libxss-dev libsqlite3-dev autoconf-archive autoconf libgdk-pixbuf-2.0-dev libqrencode-dev ``` -### openSUSE +#### openSUSE ```bash -zypper in gcc make automake autoconf libtool glib2-devel gtk2-devel libcmocka-devel libcurl-devel libexpat-devel libgpgme-devel libstrophe-devel libnotify-devel libotr-devel libuuid-devel ncurses-devel python3-devel readline-devel autoconf-archive libsignal-protocol-c-devel libgcrypt-devel sqlite3-devel gdk-pixbuf-devel qrencode-devel +sudo zypper in gcc make automake autoconf libtool glib2-devel gtk2-devel libcmocka-devel libcurl-devel libexpat-devel libgpgme-devel libstrophe-devel libnotify-devel libotr-devel libuuid-devel ncurses-devel python3-devel readline-devel autoconf-archive libsignal-protocol-c-devel libgcrypt-devel sqlite3-devel gdk-pixbuf-devel qrencode-devel ``` -### Alpine Linux (Edge) +#### Alpine Linux (Edge) ```bash -apk add build-base autoconf autoconf-archive automake libtool pkgconf libmesode-dev ncurses-dev glib-dev curl-dev readline-dev libnotify-dev libxscrnsaver libotr-dev gpgme-dev libsignal-protocol-c-dev libgcrypt-dev gtk+2.0-dev python3-dev cmocka-dev +sudo apk add build-base autoconf autoconf-archive automake libtool pkgconf libmesode-dev ncurses-dev glib-dev curl-dev readline-dev libnotify-dev libxscrnsaver libotr-dev gpgme-dev libsignal-protocol-c-dev libgcrypt-dev gtk+2.0-dev python3-dev cmocka-dev ``` Note that some of the packages for Alpine Linux are only available in the "testing" repository -### Arch Linux +#### Arch Linux ```bash -pacman -S --needed autoconf autoconf-archive automake base-devel check cmake cmocka curl doxygen expat gcc git gpgme gtk2 libgcrypt libnotify libotr libtool libxss make openssl pkg-config python wget sqlite gdk-pixbuf2 qrencode +sudo pacman -S --needed autoconf autoconf-archive automake base-devel check cmake cmocka curl doxygen expat gcc git gpgme gtk2 libgcrypt libnotify libotr libtool libxss make openssl pkg-config python wget sqlite gdk-pixbuf2 qrencode ``` -### Fedora +#### Fedora ```bash -dnf install autoconf autoconf-archive automake expect-devel gcc git glib2-devel glibc-all-langpacks gtk2-devel libXScrnSaver-devel libcmocka-devel libcurl-devel expat-devel libgcrypt-devel gpgme-devel libmicrohttpd-devel libnotify-devel libotr-devel libsignal-protocol-c-devel libtool libuuid-devel make ncurses-devel python3 python3-devel readline-devel openssl-devel sqlite-devel gdk-pixbuf2-devel qrencode-devel libstrophe-devel +sudo dnf install autoconf autoconf-archive automake expect-devel gcc git glib2-devel glibc-all-langpacks gtk2-devel libXScrnSaver-devel libcmocka-devel libcurl-devel expat-devel libgcrypt-devel gpgme-devel libmicrohttpd-devel libnotify-devel libotr-devel libsignal-protocol-c-devel libtool libuuid-devel make ncurses-devel python3 python3-devel readline-devel openssl-devel sqlite-devel gdk-pixbuf2-devel qrencode-devel libstrophe-devel ``` -### Mac OS +#### Mac OS ```bash brew install autoconf autoconf-archive automake libtool pkg-config glib gnutls gpgme libotr libstrophe openssl ossp-uuid readline terminal-notifier libsignal-protocol-c ``` -Some required packages are "keg-only", which means they are not symlinked into /usr/local, therefore pkg-config will fail when detecting the libraries and the build will fail. In order to fix this we need to add these packages to the _PKG_CONFIG_PATH.1rem_ +Some required packages are "keg-only", which means they are not symlinked into /usr/local, therefore pkg-config will fail when detecting the libraries and the build will fail. In order to fix this we need to add these packages to the `PKG_CONFIG_PATH` variable as such: -```plaintext +```bash export PKG_CONFIG_PATH="/usr/local/opt/ncurses/lib/pkgconfig:$PKG_CONFIG_PATH" export PKG_CONFIG_PATH="/usr/local/opt/expat/lib/pkgconfig:$PKG_CONFIG_PATH" export PKG_CONFIG_PATH="/usr/local/opt/curl/lib/pkgconfig:$PKG_CONFIG_PATH" @@ -131,98 +123,74 @@ export PKG_CONFIG_PATH="/usr/local/opt/openssl/lib/pkgconfig:$PKG_CONFIG_PATH" export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig:$PKG_CONFIG_PATH" ``` -### OpenBSD +#### OpenBSD ```bash -pkg_add cmake gmake cmocka libtool automake-1.16.2 pkgconf readline python-3.8.2 autoconf-2.69p2 autoconf-archive libstrophe curl gpgme glib2 gtk+2 libotr libassuan libgpg-error libgcrypt libsignal-protocol-c sqlite3 +sudo pkg_add cmake gmake cmocka libtool automake-1.16.2 pkgconf readline python-3.8.2 autoconf-2.69p2 autoconf-archive libstrophe curl gpgme glib2 gtk+2 libotr libassuan libgpg-error libgcrypt libsignal-protocol-c sqlite3 ``` -
-## Explanations +## Building and Installing CProof -
+Follow these steps to build and install CProof after obtaining the source code: -### Input files - -configure.ac – Macro definitions to configure CProof for the target environment (autoconf) - -Makefile.am – Template Makefile (automake) - -These files are the inputs to generating the actual configure script and Makefile required to configure and compile CProof. - -### Generating a configure script - -To generate the configure script: +1. **Initialize the build system** (required only when setting up for the first time or modifying `configure.ac`): ```bash ./bootstrap.sh ``` -This phase only needs to be run when changes have been made to configure.ac, however it does no harm to run it on every build. This phase also generates other files needed to create a config.h header (variables used in the main code), and a Makefile (used for compilation). +This runs `autoreconf --install` to generate the `configure` script, `config.h` header (with environment-specific variables), and `Makefile` template. It’s safe but unnecessary to run on every build if `configure.ac` is unchanged. -Why not just write configure yourself, instead of writing configure.ac and generating one with bootstrap.sh? Take a look at the generated configure script and you'll see why, there's a lot of work involved in writing a configure script. - -The bootstrap.sh file is very simple, it just runs autoreconf --install see autoreconf - -### Configuring - -Once the configure script has been generated, run it to configure CProof. +2. **Configure the build**: ```bash ./configure ``` -This will result in the following being generated, along with some other files: +This checks dependencies and generates the `Makefile` and `config.h`. If dependencies are missing, it fails with an error message. -```bash -src/config.h -Makefile -``` - -### Compiling - -The following step will then compile CProof: +3. **Compile the code**: ```bash make ``` -Once you have run ./bootstrap.sh and ./configure once, if all you are doing is making code changes, then you only need to run make to recompile your changes. +This compiles CProof, producing the `profanity` executable in the current directory. For code changes after the initial build, run `make` again to recompile. -To perform a clean build (i.e. remove all compiled files and recompile) +To perform a clean build (remove compiled files and recompile): ```bash make clean make ``` -### Tests +4. **Run tests** (optional): -All tests (unit and functional) can be run with: +To run all tests (unit and functional): ```bash make check ``` -Unit tests alone can be run with: +To run only unit tests: ```bash make check-unit ``` -### Install - -Once you have compiled CProof with make, the executable will be available in the current directory: - -```bash -./profanity -``` - -To install this version on your system, i.e. to be able to run it from anywhere: +5. **Install the executable** (optional): ```bash sudo make install ``` -This step is not really necessary when doing development (i.e. you can always run the version just compiled in the project directory), unless you want to have your development version available to any users on your system. +This installs CProof system-wide, allowing it to be run from any location (e.g., `profanity`). Root privileges are required. During development, you can run `./profanity` directly from the project directory without installing. + +## Input Files for Autotools + +The following files are key inputs to the Autotools build process: +- `configure.ac`: Defines macros to configure CProof for the target environment (processed by `autoconf`). +- `Makefile.am`: Template for generating the `Makefile` (processed by `automake`). + +These files generate the `configure` script and `Makefile` required to build CProof.