From 9bd69b1f1d71a9692189beeac75af9dfbad816cc Mon Sep 17 00:00:00 2001 From: Nicolas Dechesne Date: Fri, 26 Jun 2020 19:10:51 +0200 Subject: sphinx: initial sphinx support This commit is autogenerated pandoc to generate an inital set of reST files based on DocBook XML files. A .rst file is generated for each .xml files in all manuals with this command: cd for i in *.xml; do \ pandoc -f docbook -t rst --shift-heading-level-by=-1 \ $i -o $(basename $i .xml).rst \ done The conversion was done with: pandoc 2.9.2.1-91 (Arch Linux). Also created an initial top level index file for each document, and added all 'books' to the top leve index.rst file. The YP manuals layout is organized as: Book Chapter Section Section Section Sphinx uses section headers to create the document structure. ReStructuredText defines sections headers like that: To break longer text up into sections, you use section headers. These are a single line of text (one or more words) with adornment: an underline alone, or an underline and an overline together, in dashes "-----", equals "======", tildes "~~~~~~" or any of the non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you feel comfortable with. An underline-only adornment is distinct from an overline-and-underline adornment using the same character. The underline/overline must be at least as long as the title text. Be consistent, since all sections marked with the same adornment style are deemed to be at the same level: Let's define the following convention when converting from Docbook: Book => overline === (Title) Chapter => overline *** (1.) Section => ==== (1.1) Section => ---- (1.1.1) Section => ~~~~ (1.1.1.1) Section => ^^^^ (1.1.1.1.1) During the conversion with pandoc, we used --shift-heading-level=-1 to convert most of DocBook headings automatically. However with this setting, the Chapter header was removed, so I added it back manually. Without this setting all headings were off by one, which was more difficult to manually fix. At least with this change, we now have the same TOC with Sphinx and DocBook. (From yocto-docs rev: 3c73d64a476d4423ee4c6808c685fa94d88d7df8) Signed-off-by: Nicolas Dechesne Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-images.rst | 137 ++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 documentation/ref-manual/ref-images.rst (limited to 'documentation/ref-manual/ref-images.rst') diff --git a/documentation/ref-manual/ref-images.rst b/documentation/ref-manual/ref-images.rst new file mode 100644 index 0000000000..62863b640a --- /dev/null +++ b/documentation/ref-manual/ref-images.rst @@ -0,0 +1,137 @@ +****** +Images +****** + +The OpenEmbedded build system provides several example images to satisfy +different needs. When you issue the ``bitbake`` command you provide a +“top-level” recipe that essentially begins the build for the type of +image you want. + +.. note:: + + Building an image without GNU General Public License Version 3 + (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and + the GNU Affero General Public License Version 3 (AGPL-3.0) components + is only supported for minimal and base images. Furthermore, if you + are going to build an image using non-GPLv3 and similarly licensed + components, you must make the following changes in the + local.conf + file before using the BitBake command to build the minimal or base + image: + :: + + 1. Comment out the EXTRA_IMAGE_FEATURES line + 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" + + +From within the ``poky`` Git repository, you can use the following +command to display the list of directories within the `Source +Directory <#source-directory>`__ that contain image recipe files: $ ls +meta*/recipes*/images/*.bb + +Following is a list of supported recipes: + +- ``build-appliance-image``: An example virtual machine that contains + all the pieces required to run builds using the build system as well + as the build system itself. You can boot and run the image using + either the `VMware + Player `__ or + `VMware + Workstation `__. + For more information on this image, see the `Build + Appliance <&YOCTO_HOME_URL;/software-item/build-appliance/>`__ page + on the Yocto Project website. + +- ``core-image-base``: A console-only image that fully supports the + target device hardware. + +- ``core-image-clutter``: An image with support for the Open GL-based + toolkit Clutter, which enables development of rich and animated + graphical user interfaces. + +- ``core-image-full-cmdline``: A console-only image with more + full-featured Linux system functionality installed. + +- ``core-image-lsb``: An image that conforms to the Linux Standard Base + (LSB) specification. This image requires a distribution configuration + that enables LSB compliance (e.g. ``poky-lsb``). If you build + ``core-image-lsb`` without that configuration, the image will not be + LSB-compliant. + +- ``core-image-lsb-dev``: A ``core-image-lsb`` image that is suitable + for development work using the host. The image includes headers and + libraries you can use in a host development environment. This image + requires a distribution configuration that enables LSB compliance + (e.g. ``poky-lsb``). If you build ``core-image-lsb-dev`` without that + configuration, the image will not be LSB-compliant. + +- ``core-image-lsb-sdk``: A ``core-image-lsb`` that includes everything + in the cross-toolchain but also includes development headers and + libraries to form a complete standalone SDK. This image requires a + distribution configuration that enables LSB compliance (e.g. + ``poky-lsb``). If you build ``core-image-lsb-sdk`` without that + configuration, the image will not be LSB-compliant. This image is + suitable for development using the target. + +- ``core-image-minimal``: A small image just capable of allowing a + device to boot. + +- ``core-image-minimal-dev``: A ``core-image-minimal`` image suitable + for development work using the host. The image includes headers and + libraries you can use in a host development environment. + +- ``core-image-minimal-initramfs``: A ``core-image-minimal`` image that + has the Minimal RAM-based Initial Root Filesystem (initramfs) as part + of the kernel, which allows the system to find the first “init” + program more efficiently. See the + ```PACKAGE_INSTALL`` <#var-PACKAGE_INSTALL>`__ variable for + additional information helpful when working with initramfs images. + +- ``core-image-minimal-mtdutils``: A ``core-image-minimal`` image that + has support for the Minimal MTD Utilities, which let the user + interact with the MTD subsystem in the kernel to perform operations + on flash devices. + +- ``core-image-rt``: A ``core-image-minimal`` image plus a real-time + test suite and tools appropriate for real-time use. + +- ``core-image-rt-sdk``: A ``core-image-rt`` image that includes + everything in the cross-toolchain. The image also includes + development headers and libraries to form a complete stand-alone SDK + and is suitable for development using the target. + +- ``core-image-sato``: An image with Sato support, a mobile environment + and visual style that works well with mobile devices. The image + supports X11 with a Sato theme and applications such as a terminal, + editor, file manager, media player, and so forth. + +- ``core-image-sato-dev``: A ``core-image-sato`` image suitable for + development using the host. The image includes libraries needed to + build applications on the device itself, testing and profiling tools, + and debug symbols. This image was formerly ``core-image-sdk``. + +- ``core-image-sato-sdk``: A ``core-image-sato`` image that includes + everything in the cross-toolchain. The image also includes + development headers and libraries to form a complete standalone SDK + and is suitable for development using the target. + +- ``core-image-testmaster``: A "master" image designed to be used for + automated runtime testing. Provides a "known good" image that is + deployed to a separate partition so that you can boot into it and use + it to deploy a second image to be tested. You can find more + information about runtime testing in the "`Performing Automated + Runtime + Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__" + section in the Yocto Project Development Tasks Manual. + +- ``core-image-testmaster-initramfs``: A RAM-based Initial Root + Filesystem (initramfs) image tailored for use with the + ``core-image-testmaster`` image. + +- ``core-image-weston``: A very basic Wayland image with a terminal. + This image provides the Wayland protocol libraries and the reference + Weston compositor. For more information, see the "`Using Wayland and + Weston <&YOCTO_DOCS_DEV_URL;#dev-using-wayland-and-weston>`__" + section in the Yocto Project Development Tasks Manual. + +- ``core-image-x11``: A very basic X11 image with a terminal. -- cgit v1.2.3-54-g00ecf