Skip to content
This repository has been archived by the owner on Jan 6, 2023. It is now read-only.

Commit

Permalink
Reflow to 72 width. Removed (*) references since they weren't referri…
Browse files Browse the repository at this point in the history 
…ng to any footnotes. Corrected all occurrences of "Clear Linux OS".
  • Loading branch information
@ahkok
ahkok committed Apr 20, 2018
1 parent db111e6 commit bae66bf
Show file tree
Hide file tree
Showing 10 changed files with 579 additions and 582 deletions.
94 changes: 47 additions & 47 deletions 01-index.md
View file
Expand Up @@ -22,60 +22,60 @@ How To Clear

## Foreword

Clear Linux\* OS for Intel® Architecture was designed a long time ago
Clear Linux OS for Intel® Architecture was designed a long time ago
to fill a major gap in the existing Linux OS ecosystem. The problem
identified was that Linux OS distributions were either
updated once or twice a year, or the distro turned your system
into a dependency hell because it allowed your package management system
to combine incompatible components.

Clear Linux OS attempts to solve this problem by preventing you from
combining fundamentally incompatible components, and allowing you to
update with a frequency of several times a day, if needed. This allows
users to receive smaller updates and maintain functional software
identified was that Linux OS distributions were either updated once
or twice a year, or the distro turned your system into a dependency
hell because it allowed your package management system to combine
incompatible components.

Clear Linux OS attempts to solve this problem by preventing you from
combining fundamentally incompatible components, and allowing you to
update with a frequency of several times a day, if needed. This allows
users to receive smaller updates and maintain functional software
without the overhead of dealing with software incompatibilities.

Over the last few years, the Clear Linux OS team has consistently
delivered this in a usable form and we've used Clear Linux OS as a
vehicle to deliver much more technological advancement to users.
We've also allowed people to use our tooling to do exactly
the same, without recreating Clear Linux from scratch. Our tooling,
concepts, and content are modular and Free (as in beer and speech), and we
have published everything.

The tooling covered in this training reproduces what the Clear Linux OS
team develops and uses to create and maintain the OS. The tooling allows users
to create a derivative OS that is based on Clear Linux OS in various
degrees of similarity. Either the derivative can be entirely new and
use only the tooling provided, or the derivative can contain only minor
changes.

The training revolves around mixer from start to finish, and makes
several segues into more advanced topics that are relevant for the
whole picture. In all details, we show in precise ways how the
actual deployment of the results of the advanced topics can be pushed to
Over the last few years, the Clear Linux OS team has consistently
delivered this in a usable form and we've used Clear Linux OS as
a vehicle to deliver much more technological advancement to users.
We've also allowed people to use our tooling to do exactly the same,
without recreating Clear Linux OS from scratch. Our tooling, concepts,
and content are modular and Free (as in beer and speech), and we have
published everything.

The tooling covered in this training reproduces what the Clear Linux
OS team develops and uses to create and maintain the OS. The tooling
allows users to create a derivative OS that is based on Clear Linux
OS in various degrees of similarity. Either the derivative can be
entirely new and use only the tooling provided, or the derivative
can contain only minor changes.

The training revolves around mixer from start to finish, and makes
several segues into more advanced topics that are relevant for the
whole picture. In all details, we show in precise ways how the actual
deployment of the results of the advanced topics can be pushed to
actual target OS installations.

## About this document

This training document is a living training that will be adopted in the
future to adjust for changes in the tooling and options, as well as any
fixes that must be included.
This training document is a living training that will be adopted in
the future to adjust for changes in the tooling and options, as well
as any fixes that must be included.

The content itself is designed to be self-contained and allow someone
to use a clean Clear Linux OS installation to do the training in its
entirety. There should not be a need to install third party software,
and the training material should explain all the concepts without the
need for external reference documentation. It is expected
that people will consult manual pages where appropriate.
The content itself is designed to be self-contained and allow someone
to use a clean Clear Linux OS installation to do the training in its
entirety. There should not be a need to install third party software,
and the training material should explain all the concepts without
the need for external reference documentation. It is expected that
people will consult manual pages where appropriate.

Due to the nature of the Clear Linux OS tools, a functional network
connection is required to use many of the tools. While it is possible
to create a set of trainings that would function entirely offline, this
would be time consuming and out of date almost immediately.
Due to the nature of the Clear Linux OS tools, a functional network
connection is required to use many of the tools. While it is possible
to create a set of trainings that would function entirely offline,
this would be time consuming and out of date almost immediately.

This training is hosted on github. We appreciate any feedback and
comments, especially in the form of Pull Requests. Please visit the
This training is hosted on github. We appreciate any feedback and
comments, especially in the form of Pull Requests. Please visit the
project page to open a ticket or clone/branch the training and help us.

[how-to-clear](https://github.com/clearlinux/how-to-clear/)
Expand All @@ -88,9 +88,9 @@ focused on the topic without spending time on meta-problems.

## Need help?

The Clear Linux OS team can be reached for generic questions about
Clear Linux OS, bugs, feedback, and any relevant discussion
through the following methods:
The Clear Linux OS team can be reached for generic questions about
Clear Linux OS, bugs, feedback, and any relevant discussion through
the following methods:

* [Mailinglist](https://lists.clearlinux.org/mailman/listinfo/dev)
* [IRC](http://webchat.freenode.net?channels=%23clearlinux)
Expand Down
158 changes: 79 additions & 79 deletions 02-concepts.md
View file
@@ -1,11 +1,11 @@

How To Clear - Clear Linux\* distribution concepts
==================================================
How To Clear - Clear Linux distribution concepts
================================================

This comment has been minimized.

Sign in to view

Copy link
@sysarcher

sysarcher Sep 13, 2018

Contributor

Using the ========== marker for H1 and ## marker for H2 (and onwards) confuses some markdown previewers (I've seen at least one misbehave). Might be a good idea to replace this line in a future commit with a single # for consistency's sake.

Reference: https://github.github.com/gfm/#atx-headings

## What this document explains

In the training, we will use the Clear Linux OS Team vocabulary
to describe processes, concepts, and data. Since this vocabulary has
In the training, we will use the Clear Linux OS Team vocabulary to
describe processes, concepts, and data. Since this vocabulary has
grown over time in the team, it may not be the most logical naming for
people who start to learn about how Clear Linux OS is created. This
document attempts to explain the idea behind the terminology.
Expand All @@ -22,127 +22,127 @@ an update.

The content originates from an "update server". This is implemented by
a https enabled webserver where the files are served as static content.
The Clear Linux OS periodically queries the data on the update
server and determines whether updates are available, and in case the OS
wants to install optional components, or even when a new installation
is performed. In all those cases, the update content files provides
all the data and metadata to perform all the needed actions.
The Clear Linux OS periodically queries the data on the update server
and determines whether updates are available, and in case the OS wants
to install optional components, or even when a new installation is
performed. In all those cases, the update content files provides all
the data and metadata to perform all the needed actions.


## Bundles

In Clear Linux OS, the choice was made to do away with packages as the
smallest functional component size. One of the main reasons is that
packages in a disproportionate sense are unusable to users by
themselves, and require a large amount of packages to be installed
In Clear Linux OS, the choice was made to do away with packages as
the smallest functional component size. One of the main reasons is
that packages in a disproportionate sense are unusable to users by
themselves, and require a large amount of packages to be installed
before the functionality they offer can be used.

For example, the xorg-server package does not provide a function X
server without the presence of about 30+ additional components. On top
of that, in order to create these 30 or so components, an additional
200 or so packages are needed for various aspects of the creation of
For example, the xorg-server package does not provide a function X
server without the presence of about 30+ additional components. On top
of that, in order to create these 30 or so components, an additional
200 or so packages are needed for various aspects of the creation of
the X server binary.

In Clear Linux OS, bundles are the concept of the smallest usable
collection of packages that provide a functional component, and
traditional packages are not visible to the user. In some cases, it
could mean that a bundle effectively contains a single package (e.g.
the "curl" bundle), but in most cases a bundle contains several or even
many packages.
In Clear Linux OS, bundles are the concept of the smallest usable
collection of packages that provide a functional component, and
traditional packages are not visible to the user. In some cases, it
could mean that a bundle effectively contains a single package (e.g.
the "curl" bundle), but in most cases a bundle contains several or
even many packages.


## Manifests

The Clear Linux software update content consists of data and metadata.
The data is the files that end up in the OS. The metadata contains
relevant information to properly provision the data to the OS file
system, as well as update the system and add or remove additional
The Clear Linux OS software update content consists of data and
metadata. The data is the files that end up in the OS. The metadata
contains relevant information to properly provision the data to the OS
file system, as well as update the system and add or remove additional
content to the OS.

The Manifests are mostly long lists of hashes that describe content.
Each bundle gets its own manifest file. There is a master manifest file
that describes all manifests to tie it all together.
The Manifests are mostly long lists of hashes that describe content.
Each bundle gets its own manifest file. There is a master manifest
file that describes all manifests to tie it all together.


## Fullfiles, packs, and delta packs

The data that an update provisions to a system can be obtained in three
different ways. There are three different methods, and they exist to
optimize the delivery of content and speed up updates.
The data that an update provisions to a system can be obtained in
three different ways. There are three different methods, and they
exist to optimize the delivery of content and speed up updates.

Fullfiles are always generated for every file in every release. This
allows any Clear Linux OS to obtain the exact copy of the content for
each version directly. This would be used if the OS verification
Fullfiles are always generated for every file in every release. This
allows any Clear Linux OS to obtain the exact copy of the content
for each version directly. This would be used if the OS verification
(`swupd verify`) needed to replace a single file, for instance.

Packs are available for some releases and combine many files to speed
up the creation of installation media and large updates. Delta packs
are an optimized version of packs that only contain updates (binary
Packs are available for some releases and combine many files to speed
up the creation of installation media and large updates. Delta packs
are an optimized version of packs that only contain updates (binary
diffs) and cannot be used without having the original file content.

In most `swupd update` scenarios, the delta packs will be used as much
as possible, since they deliver the update content in the smallest size
possible.
In most `swupd update` scenarios, the delta packs will be used as much
as possible, since they deliver the update content in the smallest
size possible.

In most `swupd bundle-add` scenarios, the packs will be used as much as
possible, since they deliver the needed content in a single
In most `swupd bundle-add` scenarios, the packs will be used as
much as possible, since they deliver the needed content in a single
downloadable unit.


## Upstream

An Open Source Project is by definition "upstream". The Clear Linux OS
directly consumes project software from upstream as much as possible.
In most cases, this is trivial and the upstream community creates
proper source code releases, and addresses bugs and issues as needed
An Open Source Project is by definition "upstream". The Clear Linux OS
directly consumes project software from upstream as much as possible.
In most cases, this is trivial and the upstream community creates
proper source code releases, and addresses bugs and issues as needed
appropriately.

In some cases, the Clear Linux OS team maintains some projects as an
upstream project as well. Examples are obviously the mixer and swupd
projects.
In some cases, the Clear Linux OS team maintains some projects as
an upstream project as well. Examples are obviously the mixer and
swupd projects.

The term upstream describes a relationship where content moves from
upstream to downstream in a fluid manner, and content is generally
aimed to be submitted back to upstream but receive significant review.
This concept applies also when people create a mixed Clear Linux OS
version. In that case, the official Clear Linux OS is the upstream to
the mixed version.
The term upstream describes a relationship where content moves from
upstream to downstream in a fluid manner, and content is generally
aimed to be submitted back to upstream but receive significant review.
This concept applies also when people create a mixed Clear Linux OS
version. In that case, the official Clear Linux OS is the upstream
to the mixed version.


## Packages vs. projects

In the Clear Linux OS terminology, we separate the source code that is
in upstream repositories, and the distribution adaptation of the
In the Clear Linux OS terminology, we separate the source code that
is in upstream repositories, and the distribution adaptation of the
products of that project.

The definition of a project is the thing that is the upstream of a
package. Projects are maintained by individual maintainers. The Clear
Linux OS team does not modify the project unless they are the
upstream maintainers. In the same way, people who are maintainers of
projects are directly providing content to the Clear Linux OS, with all
the responsibilities that go with it.
The definition of a project is the thing that is the upstream of
a package. Projects are maintained by individual maintainers. The
Clear Linux OS team does not modify the project unless they are the
upstream maintainers. In the same way, people who are maintainers
of projects are directly providing content to the Clear Linux OS,
with all the responsibilities that go with it.

Packages describe how the project content is consumed. Many packages
have optional dependencies and configuration items that may or may not
be desired. On top of that, specifically targeted distributions like
Clear Linux OS may want to further patch the software to configure the
project to better work with the methods and rules that the Clear Linux
OS dictates.
Packages describe how the project content is consumed. Many packages
have optional dependencies and configuration items that may or may not
be desired. On top of that, specifically targeted distributions like
Clear Linux OS may want to further patch the software to configure
the project to better work with the methods and rules that the Clear
Linux OS dictates.


## RPM

Internally, the Clear Linux OS uses the RPM package format to bridge
the software source code and the binary software update content. The
Internally, the Clear Linux OS uses the RPM package format to bridge
the software source code and the binary software update content. The
RPM format is an intermediate way of storing content.

Note: `swupd` does *not* use or recognize the RPM file format and
the `rpm` program on a Clear Linux OS installation is *not* capable
of using RPM files.
Note: `swupd` does *not* use or recognize the RPM file format and the
`rpm` program on a Clear Linux OS installation is *not* capable of
using RPM files.

Within the build mechanisms that Clear Linux OS uses, the format is
used to store the output of the compilation process and provide
dependency relationships to the code that generates bundles. These
Within the build mechanisms that Clear Linux OS uses, the format
is used to store the output of the compilation process and provide
dependency relationships to the code that generates bundles. These
bundles rely on the RPMs dependencies, and by extension, the source
code dependency information. Using these dependencies, the mixer can
create meaningful bundles that contain the needed components to make
Expand Down

0 comments on commit bae66bf

Please sign in to comment.