From 90b1644f1e83004f43db61fd670ddc079240434b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Mon, 28 Sep 2020 17:02:45 +0200 Subject: [PATCH] docs: Update Index page --- docs/index.md | 155 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 154 insertions(+), 1 deletion(-) mode change 120000 => 100644 docs/index.md diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index 32d46ee8..00000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..083a69b6 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,154 @@ +--- +nav_order: 1 +--- + +# libostree +{: .no_toc } + +1. TOC +{:toc} + +This project is now known as "libostree", though it is still appropriate to use +the previous name: "OSTree" (or "ostree"). The focus is on projects which use +libostree's shared library, rather than users directly invoking the command line +tools (except for build systems). However, in most of the rest of the +documentation, we will use the term "OSTree", since it's slightly shorter, and +changing all documentation at once is impractical. We expect to transition to +the new name over time. + +As implied above, libostree is both a shared library and suite of command line +tools that combines a "git-like" model for committing and downloading bootable +filesystem trees, along with a layer for deploying them and managing the +bootloader configuration. + +The core OSTree model is like git in that it checksums individual files and has +a content-addressed-object store. It's unlike git in that it "checks out" the +files via hardlinks, and they thus need to be immutable to prevent corruption. +Therefore, another way to think of OSTree is that it's just a more polished +version of +[Linux VServer hardlinks](http://linux-vserver.org/index.php?title=util-vserver:Vhashify&oldid=2285). + +**Features:** + + - Transactional upgrades and rollback for the system + - Replicating content incrementally over HTTP via GPG signatures and "pinned TLS" support + - Support for parallel installing more than just 2 bootable roots + - Binary history on the server side (and client) + - Introspectable shared library API for build and deployment systems + - Flexible support for multiple branches and repositories, supporting + projects like [flatpak](https://github.com/flatpak/flatpak) which + use libostree for applications, rather than hosts. + +## Operating systems and distributions using OSTree + +[Endless OS](https://endlessos.com/) uses libostree for their host system as +well as flatpak. See +their [eos-updater](https://github.com/endlessm/eos-updater) +and [deb-ostree-builder](https://github.com/dbnicholson/deb-ostree-builder) +projects. + +Fedora derivatives use rpm-ostree (noted below); there are 3 variants using OSTree: + + - [Fedora CoreOS](https://getfedora.org/en/coreos/) + - [Fedora Silverblue](https://silverblue.fedoraproject.org/) + - [Fedora IoT](https://iot.fedoraproject.org/) + +Red Hat Enterprise Linux CoreOS is a derivative of Fedora CoreOS, used in [OpenShift 4](https://try.openshift.com/). +The [machine-config-operator](https://github.com/openshift/machine-config-operator/blob/master/docs/OSUpgrades.md) +manages upgrades. RHEL CoreOS is also the successor to RHEL Atomic Host, which +uses rpm-ostree as well. + +[GNOME Continuous](https://wiki.gnome.org/Projects/GnomeContinuous) is +where OSTree was born - as a high performance continuous delivery/testing +system for GNOME. + +[Liri OS](https://liri.io/download/silverblue/) has the option to install +their distribution using ostree. + +## Distribution build tools + +[meta-updater](https://github.com/advancedtelematic/meta-updater) is +a layer available for [OpenEmbedded](http://www.openembedded.org/wiki/Main_Page) +systems. + +[QtOTA](http://doc.qt.io/QtOTA/) is Qt's over-the-air update framework +which uses libostree. + +The [BuildStream](https://gitlab.com/BuildStream/buildstream) build and +integration tool supports importing and exporting from libostree repos. + +Fedora [coreos-assembler](https://github.com/coreos/coreos-assembler) is +the build tool used to generate Fedora CoreOS derivatives. + +## Projects linking to libostree + +[rpm-ostree](https://github.com/projectatomic/rpm-ostree) is used by the +Fedora-derived operating systems listed above. It is a full hybrid +image/package system. By default it uses libostree to atomically replicate a base OS +(all dependency resolution is done on the server), but it supports "package layering", where +additional RPMs can be layered on top of the base. This brings a "best of both worlds"" +model for image and package systems. + +[eos-updater](https://github.com/endlessm/eos-updater) is a daemon that implements updates +on EndlessOS. + +[flatpak](https://github.com/flatpak/flatpak) uses libostree for desktop +application containers. Unlike most of the other systems here, flatpak does not +use the "libostree host system" aspects (e.g. bootloader management), just the +"git-like hardlink dedup". For example, flatpak supports a per-user OSTree +repository. + +## Language bindings + +libostree is accessible via [GObject Introspection](https://gi.readthedocs.io/en/latest/); +any language which has implemented the GI binding model should work. +For example, Both [pygobject](https://pygobject.readthedocs.io/en/latest/) +and [gjs](https://gitlab.gnome.org/GNOME/gjs) are known to work +and further are actually used in libostree's test suite today. + +Some bindings take the approach of using GI as a lower level and +write higher level manual bindings on top; this is more common +for statically compiled languages. Here's a list of such bindings: + + - [ostree-go](https://github.com/ostreedev/ostree-go/) + - [ostree-rs](https://gitlab.com/fkrull/ostree-rs/) + +## Building + +Releases are available as GPG signed git tags, and most recent +versions support extended validation using +[git-evtag](https://github.com/cgwalters/git-evtag). + +However, in order to build from a git clone, you must update the +submodules. If you're packaging OSTree and want a tarball, I +recommend using a "recursive git archive" script. There are several +available online; +[this code](https://github.com/ostreedev/ostree/blob/master/packaging/Makefile.dist-packaging#L11) +in OSTree is an example. + +Once you have a git clone or recursive archive, building is the +same as almost every autotools project: + +``` +git submodule update --init +env NOCONFIGURE=1 ./autogen.sh +./configure --prefix=... +make +make install DESTDIR=/path/to/dest +``` + +## Contributing + +See [Contributing](docs/CONTRIBUTING.md). + +## Licensing + +The licensing for the *code* of libostree can be canonically found in the individual files; +and the overall status in the [COPYING](https://github.com/ostreedev/ostree/blob/master/COPYING) +file in the source. Currently, that's LGPLv2+. This also covers the man pages and API docs. + +The license for the manual documentation in the `doc/` directory is: +`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)` +This is intended to allow use by Wikipedia and other projects. + +In general, files should have a `SPDX-License-Identifier` and that is canonical.