Current sphinx/ contents are mostly WiP. Let's beat them into shape for
publishing on ReadTheDocs.
Integrate the API documentation generated with doxygen for the core C
API and C++ bindings into sphinx using breathe.
Update configure.ac to check for sphinx-build in addition to doxygen and
make the main Makefile trigger a sphinx build on `make doc` (although
the docs can also be generated without starting the build system by
running: `sphinx-build ./docs/ docs/sphinx-output`).
Move the introduction text from the main header into the relevant .rst
file.
Remove obsolete Doxyfile.in and create a static Doxygen under doc/ where
all the documentation now lives.
Update .gitignore where needed.
Reviewed-by: Vincent Fazio <vfazio@xes-inc.com>
Link: https://lore.kernel.org/r/20250211-improve-docs-v4-12-dc56702c2ca8@linaro.org
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
The release tarball building is currently broken because it looks for
a file that no longer exists. Drop the LGPL-3.0 license file from
EXTRA_DIST.
Fixes: 76ecc337c5 ("licensing: relicense C++ bindings under LGPL-2.1-or-later")
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
The tools have served as example code, but have become too complicated
to serve that purpose.
Add a set of examples that have no purpose other than providing minimal
examples of common use cases.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
In order to output a status line in silent mode and the whole command in
default mode, use the AM_V_GEN predefined automake variable when executing
external programs like doxygen and help2man.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Add an Android.bp file for Soong, the Android build system, to build
the library including C++ bindings along with all the CLI tools.
This reference Android build file will live in a contrib/ folder to
indiciate it is a less-maintained part of libgpiod. It will need to
be moved to the root directory in order to use it, though, as Soong
doesn't let Blueprint files reference sources in a parent directory.
error: external/libgpiod/contrib/Android.bp:5:1: module "libgpiod" variant "...": Path is outside directory: ../include
error: external/libgpiod/contrib/Android.bp:5:1: module "libgpiod" variant "...": Path is outside directory: ../bindings/cxx
error: external/libgpiod/contrib/Android.bp:5:1: module "libgpiod" variant "...": Path is outside directory: ../lib/*.c
error: external/libgpiod/contrib/Android.bp:5:1: module "libgpiod" variant "...": Path is outside directory: ../bindings/cxx/*.cpp
Signed-off-by: Benjamin Li <benl@squareup.com>
[Bartosz: add the build file to the release tarball generated by 'make dist']
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Add missing license text files and use the CC0-1.0 license for the
rust-specific .gitignore file.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Using LGPL-2.1 for C++ library code is an issue raised several times on
the linux-gpio mailing list. Programs using C++ libraries often include
significant portions of code generated behind the scenes from C++ headers
(via templates, default implementations etc.).
Section 3 of LGPL-3.0 clarifies the use of code defined in or generated
from C++ headers so this changset proposes to use LGPL-3.0 for all C++
library code in libgpiod.
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Acked-by: Kent Gibson <warthog618@gmail.com>
LGPL-2.1 is a license meant for shared libraries. Because I didn't know
any better I used it for all files in the repository, including programs
linking against libgpiod. The standard approach for many similar projects
is to use LGPL for library code and GPL for programs (and also Makefiles
and other files containing code or configuration).
Relicense all programs, tests, makefiles and autotools files under
GPL-2.0 or later.
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Acked-by: Kent Gibson <warthog618@gmail.com>
In order to make the licensing situation of libgpiod clear and enable
easy reusing of the code, let's make all the files in the repository
compliant with the REUSE v3.0 specification.
In order to achieve that:
- put all used licenses into a separate LICENSES/ directory
- add SPDX license identifiers to all files that were missing them with
regular text files being licensed under CC-BY-SA-4.0, while files
containing code and configuration are licensed under GPL-2.0-or-later
- replace custom copyright texts with SPDX-FileCopyrightText
- update the gpio.h kernel uAPI header with the upstream version where
the SDPX license identifier was fixed to use 'GPL-2.0-only' variant
instead of the deprecated 'GPL-2.0'
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Acked-by: Kent Gibson <warthog618@gmail.com>
This has several advantages:
* More simplified Makefile.am
* Actually used doxygen config is available as a file
* Building doc out-of-tree is possible
Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
[Bartosz: add a dependency on Doxygen to the doc target in Makefile]
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Currently the only tests we have for C++ bindings are in a simple
program that makes a lot of assumptions about the environment and
doesn't even work anymore with recent kernels.
Remove it and replace it with a proper test-suite implemented using
libgpiomockup and Catch2.
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
The src directory containing lib and tools is not necessary and will
actually cause problems if we tried to add a new component to src/
which would depend on libraries from the bindings directory because it
(bindings) already depends on src/lib.
Simplify the directory structure. Move lib and tools to the root source
directory and update all relevant files. That way we can specify the
exact build order of components from the top source Makefile.am.
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Extend the build files to automatically generate man pages for
gpio-tools using help2man if it's present in the system and we're not
cross-compiling (as the built programs must be executable for help2man
to work).
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Use the SPDX license identifier for LGPLv2.1 or later in the remaining
build and helper files.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Wrap the C API in a set of C++ classes which allow to use all libgpiod
functionalities in an object-oriented manner.
Include simplified reimplementations of gpio-tools and a set of
tests/examples showing how to use the C++ interface.
The C++ API is fully documented in doxygen.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Doxyfile was missing from release tarballs. Include it.
Reported-by: SZ Lin <sz.lin@moxa.com>
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Create a libgpiod.pc file for pkg-config. Allows to use
PKG_CHECK_MODULES([gpiod], [libgpiod >= 1.0],,) in other
autoconf-based projects.
Signed-off-by: Clemens Gruber <clemens.gruber@pqgruber.com>
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
This project contains both a library and executables so it's better to
use an umbrella term "This program ..." than "This library ..." in all
the source files.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
The license type of COPYING file is "LGPL-2.1+", but it is declared
as "LGPL-2.1" in the preamble of source files.
This patch fixes license type inconsistency issue in each source file.
Signed-off-by: SZ Lin <sz.lin@moxa.com>
[Bartosz: tweaked the commit message]
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
This is similar to the AUX directory that the autotools use to put
their files into, except that the `m4' directory will contain
autoconf macro files.
Signed-off-by: Thierry Reding <treding@nvidia.com>
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Implement a simple unit testing framework working together with the
gpio-mockup module present in the mainline linux kernel.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
The library is much less useful under GPLv3 - change the license
to the more permissive LGPLv2.1 for the entire project.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Acked-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Drop the PROJECT_NUMBER option from the Doxyfile and pass the version
to doxygen via command-line when invoking it from Makefile.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Introduce a .c file containing code that is common across all GPIO
tools but not really related to the libgpiod functionality. This file
is statically linked with every executable.
While we're at it - make gpiodetect use it right away.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Add doxygen configuration and a new target to Makefile.am to generate
documentation. Also: update gitignore.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
