summaryrefslogtreecommitdiff
path: root/Documentation
AgeCommit message (Collapse)Author
2019-07-09libcamera: Rework automatic version generation to avoid rebuildsLaurent Pinchart
Commit b817bcec6b53 ("libcamera: Auto generate version information") generates version information in order to automatically include it various locations (Sphinx and Doxygen documentation, libcamera::version variable available at runtime, and version.h available at compile time). Unfortunately this causes lots of unnecessary rebuilds when modifying the git tree state, which hinders development. The problem is caused by the generated version.h being listed as a dependency for the whole libcamera. This is required as meson (to the best of my knowledge) doesn't provide a way to explicitly specify the dependency of a single object file (camera_manager.o in this case, as camera_manager.cpp is the only consumer of the generated version string) on the custom target used to generate version.h. The dependency can't be automatically detected at build time, like dependencies on normal headers that are generated by parsing the source, because the version.h header may not exist yet. The build could then fail in a racy way. This change attempts at solving the issue by generating a version.cpp instead of a version.h to set the git-based version. This minimises the number of files that need to be rebuild when then git tree state changes, while retaining the main purpose of the original automatic version generation, the ability to access the git-based version string at runtime. We however lose the ability to access git-based version information at build time in an application building against libcamera, but there is no expected use case for this. The version string is moved from the libcamera namespace to the CameraManager class in order to avoid including version.h inside libcamera (in version.cpp and in camera_manager.cpp), which would create dependencies causing more rebuild steps, as described above. On the other hand, major, minor and patch level version numbers are useful at build time. This commit changes the generation of version.h in order to add three macros named LIBCAMERA_VERSION_MAJOR, LIBCAMERA_VERSION_MINOR and LIBCAMERA_VERSION_PATCH for this purpose. version.h is not included by any other libcamera header or source file, and thus doesn't force a rebuild of the library. The Sphinx and Doxygen documentation keep their git-based version information, which is set during the configuration of the build and then doesn't track git commits. We may want to investigate how to improve this, but given that git-based version for the documentation has very few use cases outside of tagging nightly builds, this isn't considered an issue at the moment. The documentation install directory now uses the base version string, in order to avoid increasing the number of documentation directories needlessly. This shouldn't cause any issue as the API should not change without a change to the version number. The version number generation and handling code now also standardises the version variables to not start with a 'v' prefix in meson, in order to simplify their handling. The prefix is added when generating the relevant files. Note that we go back to specifying the fallback version in the main meson.build, in the call to the project() function. For the time being I believe this should be a good compromise to avoid unnecessary recompilation, and moving the fallback version to a different file for tarball releases can be built on top of this. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2019-07-04Documentation: Wrap extended doc_install_dir lineKieran Bingham
The doc_install_dir is longer than 80 chars. Wrap it accordingly. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-07-04libcamera: Auto generate version informationKieran Bingham
Generate a version string, and provide a global string object which allows applications to interrogate the current libcamera version information. The version header is automatically updated by meson on each build. The string roughly follows the semver [0] conventions of major.minor.patch-label as a value. [0] https://semver.org/ A script (utils/gen-version.sh) is provided which is modelled upon the processing from autoconf's git-version-gen. The gen-version.sh script will look for tags in the form vX.Y as starting points for the version string. While the repository does not have any matching tags, v0.0 will be assumed, resulting in versions with both major and minor being set to '0', and the patch count resulting from the number of patches in the history to that point. Finally, a uniquely identifying shortened hash is provided from git: v0.0.509+0ec0edf7 Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-07-04Documentation: Make the project brief more expressiveKieran Bingham
The current project brief lacks any quotation marks, and causes the Doxygen API documents to show the header "libcameraframework". Replace the simplistic definition with a better brief, and ensure quotation marks are provided to maintain spacing. Fixes: 53c4d4c34fc4 ("Documentation: Generate source code documentation using Doxygen") Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-07-02libcamera: controls: Introduce control-related data typesKieran Bingham
Add a set of data types to support controls: - ControlValue stores a control type and value in a generic way - ControlId enumerates all the control identifiers - ControlIdentifier declares the types of a control and map their names - ControlInfo stores runtime information for controls - ControlList contains a set of control info and value pairs The control definitions map is generated from the controls documentation to ensure that the two will always be synchronised. Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2019-06-09Documentation: Use absolute paths for Doxygen EXCLUDE filesLaurent Pinchart
To avoid hardcoding a dependency between the source and build directories, use absolute paths for the Doxygen EXCLUDE files. The build directory can now be placed in any location, not just a direct subdirectory of the source directory. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-06-05libcamera: ipa_module_info: update struct to allow IPA matchingPaul Elder
We need a way to match pipelines with IPA modules, so add fields in IPAModuleInfo to hold the IPA module API version number, the pipeline name, and the pipeline version. The module API version is used to determine the layout of struct IPAModuleInfo. Also update IPA module tests and Doxygen accordingly. Doxygen needs to be updated to accomodate __attribute__((packed)). Signed-off-by: Paul Elder <paul.elder@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2019-05-23meson: Fix coding style in meson.build filesLaurent Pinchart
Consistently go for 4 spaces indentation, and always put a space between the colon in argument lists, as per the examples from the meson documentation. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2019-05-21libcamera: ipa_module: add IPA shared library modulePaul Elder
Implement a class to wrap around an IPA module shared object. For now, just load a struct IPAModuleInfo with symbol name ipaModuleInfo from an IPA module .so shared object. Also provide a public header file including the struct IPAModuleInfo, structured such that both C and C++ IPA modules are supported. Signed-off-by: Paul Elder <paul.elder@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2019-05-03libcamera: device_enumerator: add DeviceEnumeratorSysfs classPaul Elder
A udev-based device enumerator is not sufficient, since libudev is an optional dependency, or udev might fail. In these cases, we should fall back to using sysfs to enumerate devices. Add a DeviceEnumeratorSysfs class which is a specialization of DeviceEnumerator that uses sysfs to enumerate media devices on the system. Signed-off-by: Paul Elder <paul.elder@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2019-04-28Documentation: Drop install directive for DoxyfileNiklas Söderlund
Building the documentation reports warnings, WARNING: Project targetting '>= 0.40' but tried to use feature introduced in '0.50.0': install arg in configure_file WARNING: Project specifies a minimum meson_version '>= 0.40' but uses features which were added in newer versions: * 0.50.0: {'install arg in configure_file'} Due to the usage of the directive configure_file { install: false } in Documentation/meason.build which is introduced in meson 0.50. As we do not wish to install the Doxyfile no install_dir is set so there is no need to explicitly state that it should not be installed. Silence the warning by dropping the install directive. Fixes: 53c4d4c34fc49b95 ("Documentation: Generate source code documentation using Doxygen") Signed-off-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2019-04-27libcamera: Make libudev optionalLaurent Pinchart
libcamera depends on libudev for device enumeration. It is however useful to allow building documentation without requiring the dependency to be installed. Make the libudev dependency optional and compile the udev-based device enumerator out when libudev is not present. Note that while libcamera will compile without libudev, it will not be able to enumerate devices. A sysfs-based device enumerator is planned as a fallback but not implemented yet. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-04-19libcamera: Document documentation style and update the code accordinglyLaurent Pinchart
The documentation style for the Doxygen comment blocks is inconsistent in the library. Document the expectations and update all existing comment blocks to match. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org>
2019-02-14Documentation: coding-style: Discourage move on shared_ptr<>Jacopo Mondi
Using std::move() on return statement of a method or on the its returned value prevents the compiler from implementing copy-elision. Discourage that in the coding style document. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
2019-02-13libcamera: signal: Disconnect signal automatically on slot deletionLaurent Pinchart
When a signal is connected to a member function slot, the slot is not disconnected when the slot object is deleted. This can lead to calling a member function of a deleted object if the signal isn't disconnected manually by the slot object's destructor. Make signal handling easier by implementing a base Object class that tracks all connected signals and disconnects from them automatically when the object is deleted, using template specialization resolution in the Signal class. As inheriting from the Object class may to a too harsh requirement for Signal usage in applications, keep the existing behaviour working if the slot doesn't inherit from the Object class. We may reconsider this later and require all slot objects to inherit from the Object class. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2019-01-22utils: checkstyle: Add support for clang-formatLaurent Pinchart
clang-format produces better results than astyle as it can better match the libcamera coding style. Default to clang-format over astyle, fall back to astyle if clang-format isn't found, and add a --formatter command line option to select a formatter manually. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2019-01-21libcamera: log: Add log categoriesLaurent Pinchart
Log categories are used to group log messages by topic. Introduce support for categories by making the LOG() macro variadic. Support for configuring log level per category will be introduced in a subsequent commit. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2019-01-21Documentation: coding_style: Add object ownership rulesLaurent Pinchart
Object ownership is a complex topic that can lead to many issues, from memory leak to crashes. Document the rules that libcamera enforces to make object ownership tracking explicit. This is a first version of the rules and is expected to be expanded as the library is developed. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
2019-01-21Documentation: coding_style: Add move semantics to C++11 featuresLaurent Pinchart
Add the move semantics (move constructor and move assignment) to the allowed C++11 features, as we extensively use them for the unique and shared pointers. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org>
2019-01-16Documentation: coding_style: Allow C++11 variadic templatesLaurent Pinchart
We make use of the C++11 variadic templates feature in the signal&slot implementation, mark it as allowed in the coding style documentation. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org>
2019-01-16Documentation: Exclude pipeline handlers directoryLaurent Pinchart
The pipeline handlers don't define APIs, neither public not internal. There is thus no need to generate Doxygen documentation from thoses classes. Add them to the EXCLUDE files pattern. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2019-01-14Documentation: quieten sphinx-build outputKieran Bingham
The output of the sphinx-build for our documentation is overly verbose. Reduce this output to warnings and errors with the '-q' quiet option. Acked-by: Jacopo Mondi <jacopo@jmondi.org> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-01-11Documentation: Add placeholder for Doxygen-generated API documentationLaurent Pinchart
Until we have better Sphinx + Doxygen integration, replace the relative external link to the API documentation with a placeholder directory, which will be populated with the Doxygen-generated doc when exporting documentation to the website. This is needed as the Sphinx documentation is exported to the root of the website, linking to ../api-html is thus not possible. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-01-11Documentation: Update copyright yearsLaurent Pinchart
Happy new year :-) Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-01-11Documentation: Link to the API documentation generated by DoxygenLaurent Pinchart
Add a link in the toctree to the API documentation. sphinx doesn't seem to support relative external links, but we can trick it into thinking the link is absolute by adding '#://' at the end. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-01-11Documentation: Make the toctree more web-friendlyLaurent Pinchart
The toctree is displayed in the navigation bar at the top of the page. Add short names to the entries that replicate the names currently used on libcamera.org. Remove the link to the index and search pages, as the former is empty, and the latter can be accessed directory from the navigation bar search box. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-01-11Documentation: Add custom themeLaurent Pinchart
The theme replicates the look and feel of the libcamera.org website. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-01-08libcamera: Add signal/slot communication mechanismLaurent Pinchart
Introduce a Signal class that allows connecting event sources (signals) to event listeners (slots) without adding any boilerplate code usually associated with the observer or listener design patterns. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
2019-01-08Documentation: Suppress normal doxygen outputKieran Bingham
Enable the QUIET mode of Doxygen so that warnings and errors from Doxygen are more prominent in the build logs. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-01-02licenses: Add the Developer CoOKieran Bingham
Provide a reference copy of the Developers Certificate of Origin. Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2018-12-14Documentation: Remove | on the left side of diagramsLaurent Pinchart
There's no need to add a character on the left side of the ascii art diagrams, provided that we indent them properly. Fix it. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2018-12-14Documentation: Document the style check scriptJacopo Mondi
Add a section to the coding style documentation to explain usage of the checkstyle.py script. Signed-off-by: Jacopo Mondi <jacopo@jmondi.org> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2018-12-14Documentation: contributing: Mark command line as shell code-blockLaurent Pinchart
The git clone command line is a (single line) block of shell code, mark it appropriately. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2018-12-14Documentation: coding-style: Fix list indentationLaurent Pinchart
The various lists in the document are not quoted blocks. Don't indent them. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2018-12-14Documentation: Add architecture documentationLaurent Pinchart
The documentation is copied mostly verbatim from the website, with small modifications to the ascii art diagrams to make them compile. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2018-12-14Documentation: contributing: Add links to libcamera git and linuxtv.orgLaurent Pinchart
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2018-12-14Documentation: Remove _static and _templates directoryLaurent Pinchart
sphinx only requires those directories to be present because they're referenced in the configuration file. Remove the references and the directories. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2018-12-13Documentation: Add coding style documentJacopo Mondi
Add document to summarize the coding style adopted by libcamera. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
2018-12-12Documentation: Generate source code documentation using DoxygenLaurent Pinchart
Extend the documentation build system to automatically generate documentation from source code using Doxygen. This is currently separate from the sphinx documentation, and should be integrated using the breathe (and possibly exhale) extensions. As the Documentation/meson.build file needs to reference the variables holding the source files, move the Documentation directory to the end of the subdirs() in the top-level meson.build. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2018-12-12Documentation: Don't hardcode install directoryLaurent Pinchart
Use the datadir option to select the directory in which to install documentation. This defaults to $prefix/share so this doesn't introduce any change in the default case. While at it use join_paths() to join patch components instead of hardcoding the / separator. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2018-12-11Documentation: Set install_dir in custom_target()Laurent Pinchart
The custom_target() function accepts an install_dir parameter. Along with setting install to true, this can be used to replace the install_subdir() function. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2018-11-28Documentation: Introduce sphinx documentationKieran Bingham
Utilise sphinx-build to generate documentation in HTML form, and populate with some initial content. An initial conf.py is generated from sphinx-quickstart and answering initial questions. Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>