From 015d44d58d7ed0f9a4d6b0100f77ecf402b4b895 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Mon, 28 Sep 2020 16:55:03 +0200 Subject: [PATCH 1/6] docs: Add Jekyll and theme config --- docs/_config.yml | 40 ++++++++++++++++++++++++++++ docs/_sass/color_schemes/coreos.scss | 1 + 2 files changed, 41 insertions(+) create mode 100644 docs/_config.yml create mode 100644 docs/_sass/color_schemes/coreos.scss diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..2070f1cf --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,40 @@ +title: ostreedev/ostree +description: ostree documentation +baseurl: "/ostree" +url: "https://coreos.github.io" +# Comment above and use below for local development +# url: "http://localhost:4000" +permalink: /:title/ +markdown: kramdown + +remote_theme: coreos/just-the-docs +plugins: + - jekyll-remote-theme + +color_scheme: coreos + +# Aux links for the upper right navigation +aux_links: + "OSTree on GitHub": + - "https://github.com/ostreedev/ostree" + +footer_content: "Copyright © Red Hat, Inc. and others." + +# Footer last edited timestamp +last_edit_timestamp: true +last_edit_time_format: "%b %e %Y at %I:%M %p" + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true +gh_edit_link_text: "Edit this page on GitHub" +gh_edit_repository: "https://github.com/ostreedev/ostree" +gh_edit_branch: "master" +gh_edit_view_mode: "tree" + +compress_html: + clippings: all + comments: all + endings: all + startings: [] + blanklines: false + profile: false diff --git a/docs/_sass/color_schemes/coreos.scss b/docs/_sass/color_schemes/coreos.scss new file mode 100644 index 00000000..a4554be8 --- /dev/null +++ b/docs/_sass/color_schemes/coreos.scss @@ -0,0 +1 @@ +$link-color: #53a3da; 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 2/6] 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. From 6ca312a92399c92b60d83eae161a8b8ea148989b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Wed, 30 Sep 2020 19:22:29 +0200 Subject: [PATCH 3/6] docs: Update Contributing and tutorial pages --- docs/CONTRIBUTING.md | 25 +++++++++++++++---------- docs/contributing-tutorial.md | 21 +++++++-------------- 2 files changed, 22 insertions(+), 24 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index de14c380..912ea4a8 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,5 +1,14 @@ -Submitting patches ------------------- +--- +nav_order: 19 +--- + +# Contributing +{: .no_toc } + +1. TOC +{:toc} + +## Submitting patches A majority of current maintainers prefer the GitHub pull request model, and this motivated moving the primary git repository to @@ -26,8 +35,7 @@ Alternative methods if you don't like GitHub (also fully supported): It is likely however once a patch is ready to apply a maintainer will push it to a GitHub PR, and merge via Homu. -Commit message style --------------------- +## Commit message style Please look at `git log` and match the commit log style, which is very similar to the @@ -66,15 +74,13 @@ For more information see [How to Write a Git Commit Message](https://chris.beams To edit the message from the most recent commit run `git commit --amend`. To change older commits on the branch use `git rebase -i`. For a successful rebase have the branch track `upstream master`. Once the changes have been made and saved, run `git push --force origin `. -Running the test suite ----------------------- +## Running the test suite OSTree uses both `make check` and supports the [Installed Tests](https://wiki.gnome.org/GnomeGoals/InstalledTests) model as well (if `--enable-installed-tests` is provided). -Coding style ------------- +## Coding style Indentation is GNU. Files should start with the appropriate mode lines. @@ -168,7 +174,6 @@ Instead do this: } } -Contributing Tutorial ---------------------- +## Contributing Tutorial For a detailed walk-through on building, modifying, and testing, see this [tutorial on how to start contributing to OSTree](contributing-tutorial.md). diff --git a/docs/contributing-tutorial.md b/docs/contributing-tutorial.md index 47d0a1e9..bb656f0e 100644 --- a/docs/contributing-tutorial.md +++ b/docs/contributing-tutorial.md @@ -1,21 +1,14 @@ +--- +nav_order: 20 +--- + # OSTree Contributing Tutorial +{: .no_toc } The following guide is about OSTree forking, building, adding a command, testing the command, and submitting the change. -- [Getting Started](#getting-started) -- [Building OSTree](#building-ostree) - - [Install Build Dependencies](#install-build-dependencies) - - [OSTree Build Commands](#ostree-build-commands) -- [Testing a Build](#testing-a-build) - - [Testing in a Container](#testing-in-a-container) - - [Testing in a Virtual Machine](#testing-in-a-virtual-machine) -- [Tutorial: Adding a basic builtin command to OSTree](#tutorial-adding-a-basic-builtin-command-to-ostree) - - [Modifying OSTree](#modifying-ostree) - - [OSTree Tests](#ostree-tests) - - [Submitting a Patch](#submitting-a-patch) - - [Returning Workflow](#returning-workflow) - ---- +1. TOC +{:toc} ## Getting Started From 68ac9e9c50d0e190a5a82bef5fdea29bd46fdd0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Fri, 2 Oct 2020 14:34:33 +0200 Subject: [PATCH 4/6] docs: Move and update pages from the manual --- docs/{manual => }/adapting-existing.md | 8 ++++++++ docs/{manual => }/atomic-upgrades.md | 8 ++++++++ docs/{manual => }/buildsystem-and-repos.md | 8 ++++++++ docs/{manual => }/deployment.md | 8 ++++++++ docs/{manual => }/formats.md | 8 ++++++++ docs/{manual => }/introduction.md | 8 ++++++++ docs/{manual => }/related-projects.md | 8 ++++++++ docs/{manual => }/repo.md | 8 ++++++++ docs/{manual => }/repository-management.md | 8 ++++++++ 9 files changed, 72 insertions(+) rename docs/{manual => }/adapting-existing.md (99%) rename docs/{manual => }/atomic-upgrades.md (99%) rename docs/{manual => }/buildsystem-and-repos.md (99%) rename docs/{manual => }/deployment.md (99%) rename docs/{manual => }/formats.md (99%) rename docs/{manual => }/introduction.md (99%) rename docs/{manual => }/related-projects.md (99%) rename docs/{manual => }/repo.md (99%) rename docs/{manual => }/repository-management.md (99%) diff --git a/docs/manual/adapting-existing.md b/docs/adapting-existing.md similarity index 99% rename from docs/manual/adapting-existing.md rename to docs/adapting-existing.md index 3a1b8d69..cc4b76d2 100644 --- a/docs/manual/adapting-existing.md +++ b/docs/adapting-existing.md @@ -1,4 +1,12 @@ +--- +nav_order: 6 +--- + # Adapting existing mainstream distributions +{: .no_toc } + +1. TOC +{:toc} ## System layout diff --git a/docs/manual/atomic-upgrades.md b/docs/atomic-upgrades.md similarity index 99% rename from docs/manual/atomic-upgrades.md rename to docs/atomic-upgrades.md index f2c01cc1..3ddd8b40 100644 --- a/docs/manual/atomic-upgrades.md +++ b/docs/atomic-upgrades.md @@ -1,4 +1,12 @@ +--- +nav_order: 5 +--- + # Atomic Upgrades +{: .no_toc } + +1. TOC +{:toc} ## You can turn off the power anytime you want... diff --git a/docs/manual/buildsystem-and-repos.md b/docs/buildsystem-and-repos.md similarity index 99% rename from docs/manual/buildsystem-and-repos.md rename to docs/buildsystem-and-repos.md index fbae0322..6d506b4e 100644 --- a/docs/manual/buildsystem-and-repos.md +++ b/docs/buildsystem-and-repos.md @@ -1,4 +1,12 @@ +--- +nav_order: 8 +--- + # Writing a buildsystem and managing repositories +{: .no_toc } + +1. TOC +{:toc} OSTree is not a package system. It does not directly support building source code. Rather, it is a tool for transporting and managing diff --git a/docs/manual/deployment.md b/docs/deployment.md similarity index 99% rename from docs/manual/deployment.md rename to docs/deployment.md index afbcbabb..1ea7ea46 100644 --- a/docs/manual/deployment.md +++ b/docs/deployment.md @@ -1,4 +1,12 @@ +--- +nav_order: 4 +--- + # Deployments +{: .no_toc } + +1. TOC +{:toc} ## Overview diff --git a/docs/manual/formats.md b/docs/formats.md similarity index 99% rename from docs/manual/formats.md rename to docs/formats.md index 884b1b5e..36d395bd 100644 --- a/docs/manual/formats.md +++ b/docs/formats.md @@ -1,4 +1,12 @@ +--- +nav_order: 7 +--- + # OSTree data formats +{: .no_toc } + +1. TOC +{:toc} ## On the topic of "smart servers" diff --git a/docs/manual/introduction.md b/docs/introduction.md similarity index 99% rename from docs/manual/introduction.md rename to docs/introduction.md index c0113f5d..a6fa2252 100644 --- a/docs/manual/introduction.md +++ b/docs/introduction.md @@ -1,4 +1,12 @@ +--- +nav_order: 2 +--- + # OSTree Overview +{: .no_toc } + +1. TOC +{:toc} ## Introduction diff --git a/docs/manual/related-projects.md b/docs/related-projects.md similarity index 99% rename from docs/manual/related-projects.md rename to docs/related-projects.md index 429b46b9..7ddf043f 100644 --- a/docs/manual/related-projects.md +++ b/docs/related-projects.md @@ -1,4 +1,12 @@ +--- +nav_order: 10 +--- + # Related Projects +{: .no_toc } + +1. TOC +{:toc} OSTree is in many ways very evolutionary. It builds on concepts and ideas introduced from many different projects such as diff --git a/docs/manual/repo.md b/docs/repo.md similarity index 99% rename from docs/manual/repo.md rename to docs/repo.md index 8746163e..5cc59bf1 100644 --- a/docs/manual/repo.md +++ b/docs/repo.md @@ -1,4 +1,12 @@ +--- +nav_order: 3 +--- + # Anatomy of an OSTree repository +{: .no_toc } + +1. TOC +{:toc} ## Core object types and data model diff --git a/docs/manual/repository-management.md b/docs/repository-management.md similarity index 99% rename from docs/manual/repository-management.md rename to docs/repository-management.md index 77519fb9..11fe2f40 100644 --- a/docs/manual/repository-management.md +++ b/docs/repository-management.md @@ -1,4 +1,12 @@ +--- +nav_order: 9 +--- + # Managing content in OSTree repositories +{: .no_toc } + +1. TOC +{:toc} Once you have a build system going, if you actually want client systems to retrieve the content, you will quickly feel a need for From 13844c6b3e8e60fdab1c207a350d6dc274450bc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Fri, 2 Oct 2020 14:38:20 +0200 Subject: [PATCH 5/6] docs: Move historical README to the docs --- README-historical.md => docs/README-historical.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) rename README-historical.md => docs/README-historical.md (98%) diff --git a/README-historical.md b/docs/README-historical.md similarity index 98% rename from README-historical.md rename to docs/README-historical.md index 732f8bdc..eebf5b2f 100644 --- a/README-historical.md +++ b/docs/README-historical.md @@ -1,6 +1,11 @@ -This file is outdated, but some of the text here is still useful for +--- +nav_order: 99 +title: Historical OSTree README +--- + +**This file is outdated, but some of the text here is still useful for historical context. I'm preserving it (explicitly still in the tree) -for posterity. +for posterity.** OSTree ====== @@ -49,7 +54,7 @@ Comparison with existing tools Now your system is in an undefined state. You can use e.g. rpm -qV to try to find out what you overwrote, but neither dpkg nor rpm will help clean up any files left over that aren't shipped by - the old package. + the old package. This is most realistic option for people hacking on system components currently, but ostree will be better. @@ -205,7 +210,7 @@ handling of binaries is very generic and unoptimized. In contrast, ostree is explicitly designed for binaries, and in particular one type of binary - ELF executables (or it will be once we -start using bsdiff). +start using bsdiff). Another big difference versus git is that ostree uses hard links between "checkouts" and the repository. This means each checkout uses From 797eb3b14f840c960c218c6abfa68dc19e2839ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Ravier?= Date: Fri, 2 Oct 2020 14:40:16 +0200 Subject: [PATCH 6/6] README: Update and mention new docs --- README.md | 39 +++++++++++++-------------------------- 1 file changed, 13 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 1ef8e302..be6f6453 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,4 @@ -libostree ---------- - -New! See the docs online at [Read The Docs (OSTree)](https://ostree.readthedocs.org/en/latest/ ) - ------ +# libostree 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 @@ -36,8 +31,12 @@ version of projects like [flatpak](https://github.com/flatpak/flatpak) which use libostree for applications, rather than hosts. -Operating systems and distributions using OSTree ---------------------- +## Documentation + +For more information, see the [project documentation](docs/index.md) or the +[project documentation website](https://ostreedev.github.io/ostree). + +## Operating systems and distributions using OSTree [Endless OS](https://endlessos.com/) uses libostree for their host system as well as flatpak. See @@ -63,8 +62,7 @@ system for GNOME. [Liri OS](https://liri.io/download/silverblue/) has the option to install their distribution using ostree. -Distribution build tools ------------------------- +## Distribution build tools [meta-updater](https://github.com/advancedtelematic/meta-updater) is a layer available for [OpenEmbedded](http://www.openembedded.org/wiki/Main_Page) @@ -79,8 +77,7 @@ 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 ------------------------------ +## 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 @@ -98,8 +95,7 @@ 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 ----- +## 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. @@ -114,8 +110,7 @@ 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 --------- +## Building Releases are available as GPG signed git tags, and most recent versions support extended validation using @@ -139,19 +134,11 @@ make make install DESTDIR=/path/to/dest ``` -More documentation ------------------- - -New! See the docs online at [Read The Docs (OSTree)](https://ostree.readthedocs.org/en/latest/ ) - -Contributing ------------- +## Contributing See [Contributing](docs/CONTRIBUTING.md). - -Licensing -------- +## 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)