EvolutionOS
/
evolution-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Migrated, also removed codeberg from everywhere

This commit is contained in:
Tracker-Friendly 2023-10-24 00:47:09 +01:00
commit 9698188caa
111 changed files with 10011 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
.github/ISSUE_TEMPLATE/bug-report.md vendored Normal file
View File

@ -0,0 +1,12 @@
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''
---
*Before opening an issue, please be sure to check [what content is suitable for the Handbook](https://docs.voidlinux.org/about/about-this-handbook.html).*
We prioritise issues about information specific to Void, and try to avoid duplicating information already available elsewhere (e.g. on the Arch wiki).

12
.github/ISSUE_TEMPLATE/feature-request.md vendored Normal file
View File

@ -0,0 +1,12 @@
---
name: Feature request
about: Suggest an idea for the Handbook
title: ''
labels: ''
assignees: ''
---
*Before opening a request, please be sure to check [what content is suitable for the Handbook](https://docs.voidlinux.org/about/about-this-handbook.html).*
We prioritise requests for information specific to Void, and try to avoid duplicating information already available elsewhere (e.g. on the Arch wiki).

3
.github/pull_request_template.md vendored Normal file
View File

@ -0,0 +1,3 @@
Before submitting a pull request, please read [CONTRIBUTING](https://github.com/void-linux/void-docs/blob/master/CONTRIBUTING.md); pull requests that do not meet the criteria described there will not be merged. Note that this repository's CONTRIBUTING contains information specific to this repository, and is not the same as CONTRIBUTING for the void-packages repository.
We prioritise pull requests involving information specific to Void over those involving information applicable to Linux in general.

42
.github/workflows/ci.yaml vendored Normal file
View File

@ -0,0 +1,42 @@
name: Check PR
on:
pull_request:
paths:
- 'src/**'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
contents:
name: Check formatting and links
runs-on: ubuntu-latest
container:
image: ghcr.io/void-linux/void-linux:latest-full-x86_64-musl
steps:
- name: Prepare container
run: |
xbps-install -Syu || xbps-install -Syu xbps
xbps-install -yu
xbps-install -y mdbook-linkcheck vmdfmt git findutils bash
- name: Checkout
id: checkout
uses: classabbyamp/treeless-checkout-action@v1
- name: Check summary
if: steps.checkout.conclusion == 'success'
run: res/ci/check-summary.sh
- name: Check formatting
if: success() || failure()
run: res/ci/format.sh
- name: Check links
if: success() || failure()
run: res/ci/linkcheck.sh
commits:
name: Check commits
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: classabbyamp/treeless-checkout-action@v1
- name: Check commit messages
run: res/ci/commit-lint.sh

5
.gitignore vendored Normal file
View File

@ -0,0 +1,5 @@
book/
mandoc/
res/void-docs
res/void-docs.1
res/handbook-cover.png

358
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,358 @@
# Contributing
To contribute to the EvolutionOS documentation, please read the following. Pull
requests that do not meet the criteria described below will not be merged.
Before submitting a PR:
- try to address as many of the criteria as possible; and
- run the `check.sh` script provided in the repository root, addressing any
issues it reports.
This will improve the chances of your contribution being accepted quickly.
## Contents
- [Suitable Content](#suitable-content)
- [Style Guide](#style-guide)
- [Submitting Changes](#submitting-changes)
## Suitable content
The Handbook is not intended to be a general guide to using a Linux system, as
[noted in the "About"
section](https://evolution-linux.github.io/wiki/about/about-this-handbook.html):
> This handbook is not an extensive guide on how to use and configure common
> Linux software. The purpose of this document is to explain how to install,
> configure, and maintain EvolutionOS systems, and to highlight the differences
> between common Linux distributions and EvolutionOS ...
>
> Those looking for tips and tricks on how to configure a Linux system in
> general should consult upstream software documentation. Additionally, the Arch
> Wiki provides a fairly comprehensive outline of common Linux software
> configuration, and a variety of internet search engines are available for
> further assistance.
Thus, we are unlikely to accept contributions which add information that is not
particularly Evolution-specific.
## Style Guide
This style guide outlines the standards for contributing to the Handbook. The
manual on <https://evolution-linux.github.io/wiki> is generated from an
[mdBook](https://rust-lang.github.io/mdBook/) stored in the
[evolution-docs](https://github.com/evolution-linux/evolution-docs/) repository.
### General
Although there will always be cases where command listings are appropriate, the
contents of the Handbook should be written in American English.
Outside of the 'installation' sections, step-by-step instructions containing
'magic' commands for copying-and-pasting are strongly discouraged. Users are
expected to read the canonical documentation (e.g. man pages) for individual
programs to understand how to use them, rather than relying on
copying-and-pasting.
Command code-blocks should not be used to describe routine tasks documented
elsewhere in this Handbook. For example, when writing documentation for the
`foo` package, do not provide a command code-block stating that one should
install it via `xbps-install foo`. Similarly, do not provide code blocks
describing how to enable the `foo` service.
### Formatting
For markdown formatting, the
[evolution-docs](https://github.com/evolution-linux/evolution-docs/) project uses the
[Versioned Markdown](https://github.com/bobertlo/vmd) format, and enforces use
of the auto-formatter `vmdfmt`, which works very similarly to `gofmt`. Most
valid markdown is accepted by the formatter. The output format is described in
the project's [README](https://github.com/bobertlo/vmd/blob/master/README.md).
After installing the `vmdfmt` package, you can format a file by running:
```
vmdfmt -w <filepath>
```
To format the entire mdbook from the repository root, outputting a list of files
modified, run:
```
vmdfmt -w -l <filepath>
```
`vmdfmt` is used by the evolution-docs repository's `check.sh` script, which must be
[run locally before submitting a pull request](#making-changes).
### Commands
Command code-blocks should start with a `#` or `$` character, indicating whether
the command should be run as `root` or a regular user, respectively.
For example:
```
# vi /etc/fstab
```
and not:
```
$ sudo vi /etc/fstab
```
and also not:
```
vi /etc/fstab
```
Command code-blocks should be introduced with a colon (':'), i.e.:
> For example:
>
> `$ ls -l`
#### Placeholders
Placeholders indicate where the user should substitute the appropriate
information. They should use angle brackets (`<` and `>`) and contain only
lower-case text, with words separated by underscores. For example:
```
# ln -s /etc/sv/<service_name> /var/service/
```
and not:
```
# ln -s /etc/sv/[SERVICENAME] /var/service/
```
### Links
Link text should not include sentence-level punctuation. For example:
```
[Visit this site](https://example.org).
```
and not:
```
[Visit this site.](https://example.org)
```
#### Internal links
Links to other sections of the Handbook must be relative. For example:
```
[example](./example.md#heading-text)
```
and not:
```
[example](example.md#heading-text)
```
When referring literally to a Handbook section, the section title should be
placed in double-quotes. Otherwise, double-quotes are not required. For example:
```
For more information, please read the "[Power Management](./power-management.md)" section.
```
and
```
EvolutionOS provides facilities to assist with [power management](./power-management.md).
```
#### Man Page Links
The first reference to a command or man page must be a link to the relevant man
page on `https://man.voidlinux.org/`.
The link text must contain the title section number in parenthesis, and contain
no formatting. For example: [man(1)](https://man.voidlinux.org/man.1), not
[`man(1)`](https://man.voidlinux.org/man.1).
#### Auto Links
Auto links (links with the same title as URL) should use the following notation:
```
<https://www.example.com/>
```
They should not be formatted like this:
```
[https://www.example.com/](https://www.example.com/)
```
#### Checking links
If you're including new links (either internal or external) in the docs or
changing the current file structure, you should make use of the
`mdbook-linkcheck` package:
```
$ mdbook-linkcheck -s
```
This will verify all the references, and warn you if there are any issues. If
any link you're using is correct but generating errors for some reason, you can
add its domain to the exclude list in `book.toml`, under the
`[mdbook.linkcheck]` key.
`mdbook-linkcheck` is used by the evolution-docs repository's `check.sh` script,
which must be [run locally before submitting a pull request](#making-changes).
#### Redirects
When changing a section name, or moving a section to a different part of the
Handbook, a redirect must be added to the `[output.html.redirect]` section in
`book.toml`, e.g.
```
"/example.html" = "/new-location/example.html"
```
### Case
Proper nouns outside of code blocks should use the casing of official
information sources: e.g. 'runit' not 'Runit', 'DKMS' not 'dkms', 'GRUB' not
'Grub' or 'grub', etc. In general, abbreviations should be upper-cased: 'CPU'
for central processing unit, 'SSD' for solid state drive, 'UI' for user
interface, etc.
Handbook filenames and directories should use [kebab
case](https://en.wikipedia.org/wiki/Kebab_case) when splitting words. For
example the filename should be `post-install.md` not `postinstall.md`. Words
that are part of trademarks or well-known package names are exempt from this
rule: for example, `PulseAudio` and `NetworkManager` are well-known by their
[camel-case](https://en.wikipedia.org/wiki/Camel_case) names.
### Voice
Prefer the active imperative voice when writing documentation. Consider the
following examples:
> Now we need to install the CUPS drivers and configure them.
This version is conversational and friendlier, but contains unnecessary language
that may not be as clear to an ESL reader.
> Install and configure the CUPS drivers, then configure them as shown.
This version contains a clear command to act, and a follow up that shows what
will be done next. It is clear both to native English speakers, ESL readers, and
to translators.
### Warnings
Warnings should begin with `**Warning**:`, and should not be block-quoted with
`>`. For example, the Markdown should look like:
```
**Warning**: Selecting the wrong option will set your printer on fire.
```
and not:
```
> WARNING: Selecting the wrong option will set your printer on fire.
```
### Notes
Notes should only be used sparingly, and for non-critical information. They
should begin with a phrase such as "Note that ..." or "It should be noted that
... ", and not be block-quoted with `>`. For example, the Markdown should look
like:
```
Note that you can also use program X for this purpose.
```
and not:
```
> You can also use program X for this purpose.
```
### Block quotes
Block quotes (i.e. `>`) should only be used to quote text from an external
source.
## Submitting Changes
Proposed changes should be submitted as pull requests to the
[evolution-docs](https://github.com/evolution-linux/evolution-docs) repository on
[GitHub](https://github.com/). Please note that, unlike a wiki, submissions will
be reviewed before they are merged. If any changes are required they will need
to be made before the pull request is accepted. This process is in place to
ensure the quality and standards of the Handbook are sustained.
### Requirements
To clone the repository and push changes,
[git(1)](https://man.voidlinux.org/git.1) is required. It can be installed via
the `git` package.
Building the Handbook locally requires
[mdBook](https://rust-lang.github.io/mdBook/), which can be installed via the
`mdBook` package.
### Forking
To fork the repository a [GitHub account](https://github.com/join) is needed.
Once you have an account, follow GitHub's
[guide](https://help.github.com/en/articles/fork-a-repo) on setting up a fork.
Clone the repository onto your computer, enter it, and create a new branch:
```
$ git clone https://github.com/<your_username>/evolution-docs.git
$ cd evolution-docs
$ git checkout -b <branch_name>
```
You can then edit the repository files as appropriate.
### Making changes
To serve the docs locally and view your changes, run `mdbook serve` from the
root of the repository.
Once you're satisfied with your changes, run the `check.sh` script provided in
the repository root. This will run the `vmdfmt` command, which will wrap the
text appropriately, and the `mdbook-linkcheck` command, which will check for
broken links. Address any issues raised by `check.sh`.
Once `check.sh` runs without errors, push your changes to your forked
repository:
```
$ git add <edited_file(s)>
$ git commit -m "<commit_message>"
$ git push --set-upstream origin <branch_name>
```
The commit message should be in the form `<filename>: <description_of_changes>`.
Pull requests should only contain a single commit. If a change is made after the
initial commit, `git add` the changed files and then run `git commit --amend`.
The updated commit will need to be force-pushed: `git push --force`.
If multiple commits are made they will need to be squashed into a single commit
with `git rebase -i HEAD~X`, where `X` is the number of commits that need to be
squashed. An editor will appear to choose which commits to squash. A second
editor will appear to choose the commit message. See
[git-rebase(1)](https://man.voidlinux.org/git-rebase.1) for more information.
The updated commit will need to be force-pushed: `git push --force`.

427
LICENSE Normal file
View File

@ -0,0 +1,427 @@
Attribution-ShareAlike 4.0 International
=======================================================================
Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.
Considerations for licensors: Our public licenses are
intended for use by those authorized to give the public
permission to use material in ways otherwise restricted by
copyright and certain other rights. Our licenses are
irrevocable. Licensors should read and understand the terms
and conditions of the license they choose before applying it.
Licensors should also secure all rights necessary before
applying our licenses so that the public can reuse the
material as expected. Licensors should clearly mark any
material not subject to the license. This includes other CC-
licensed material, or material used under an exception or
limitation to copyright. More considerations for licensors:
wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public
licenses, a licensor grants the public permission to use the
licensed material under specified terms and conditions. If
the licensor's permission is not necessary for any reason--for
example, because of any applicable exception or limitation to
copyright--then that use is not regulated by the license. Our
licenses grant only permissions under copyright and certain
other rights that a licensor has authority to grant. Use of
the licensed material may still be restricted for other
reasons, including because others have copyright or other
rights in the material. A licensor may make special requests,
such as asking that all changes be marked or described.
Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More considerations
for the public:
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
Creative Commons Attribution-ShareAlike 4.0 International Public
License
By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution-ShareAlike 4.0 International Public License ("Public
License"). To the extent this Public License may be interpreted as a
contract, You are granted the Licensed Rights in consideration of Your
acceptance of these terms and conditions, and the Licensor grants You
such rights in consideration of benefits the Licensor receives from
making the Licensed Material available under these terms and
conditions.
Section 1 -- Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material
and in which the Licensed Material is translated, altered,
arranged, transformed, or otherwise modified in a manner requiring
permission under the Copyright and Similar Rights held by the
Licensor. For purposes of this Public License, where the Licensed
Material is a musical work, performance, or sound recording,
Adapted Material is always produced where the Licensed Material is
synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright
and Similar Rights in Your contributions to Adapted Material in
accordance with the terms and conditions of this Public License.
c. BY-SA Compatible License means a license listed at
creativecommons.org/compatiblelicenses, approved by Creative
Commons as essentially the equivalent of this Public License.
d. Copyright and Similar Rights means copyright and/or similar rights
closely related to copyright including, without limitation,
performance, broadcast, sound recording, and Sui Generis Database
Rights, without regard to how the rights are labeled or
categorized. For purposes of this Public License, the rights
specified in Section 2(b)(1)-(2) are not Copyright and Similar
Rights.
e. Effective Technological Measures means those measures that, in the
absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright
Treaty adopted on December 20, 1996, and/or similar international
agreements.
f. Exceptions and Limitations means fair use, fair dealing, and/or
any other exception or limitation to Copyright and Similar Rights
that applies to Your use of the Licensed Material.
g. License Elements means the license attributes listed in the name
of a Creative Commons Public License. The License Elements of this
Public License are Attribution and ShareAlike.
h. Licensed Material means the artistic or literary work, database,
or other material to which the Licensor applied this Public
License.
i. Licensed Rights means the rights granted to You subject to the
terms and conditions of this Public License, which are limited to
all Copyright and Similar Rights that apply to Your use of the
Licensed Material and that the Licensor has authority to license.
j. Licensor means the individual(s) or entity(ies) granting rights
under this Public License.
k. Share means to provide material to the public by any means or
process that requires permission under the Licensed Rights, such
as reproduction, public display, public performance, distribution,
dissemination, communication, or importation, and to make material
available to the public including in ways that members of the
public may access the material from a place and at a time
individually chosen by them.
l. Sui Generis Database Rights means rights other than copyright
resulting from Directive 96/9/EC of the European Parliament and of
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially
equivalent rights anywhere in the world.
m. You means the individual or entity exercising the Licensed Rights
under this Public License. Your has a corresponding meaning.
Section 2 -- Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License,
the Licensor hereby grants You a worldwide, royalty-free,
non-sublicensable, non-exclusive, irrevocable license to
exercise the Licensed Rights in the Licensed Material to:
a. reproduce and Share the Licensed Material, in whole or
in part; and
b. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where
Exceptions and Limitations apply to Your use, this Public
License does not apply, and You do not need to comply with
its terms and conditions.
3. Term. The term of this Public License is specified in Section
6(a).
4. Media and formats; technical modifications allowed. The
Licensor authorizes You to exercise the Licensed Rights in
all media and formats whether now known or hereafter created,
and to make technical modifications necessary to do so. The
Licensor waives and/or agrees not to assert any right or
authority to forbid You from making technical modifications
necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective
Technological Measures. For purposes of this Public License,
simply making modifications authorized by this Section 2(a)
(4) never produces Adapted Material.
5. Downstream recipients.
a. Offer from the Licensor -- Licensed Material. Every
recipient of the Licensed Material automatically
receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this
Public License.
b. Additional offer from the Licensor -- Adapted Material.
Every recipient of Adapted Material from You
automatically receives an offer from the Licensor to
exercise the Licensed Rights in the Adapted Material
under the conditions of the Adapter's License You apply.
c. No downstream restrictions. You may not offer or impose
any additional or different terms or conditions on, or
apply any Effective Technological Measures to, the
Licensed Material if doing so restricts exercise of the
Licensed Rights by any recipient of the Licensed
Material.
6. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You
are, or that Your use of the Licensed Material is, connected
with, or sponsored, endorsed, or granted official status by,
the Licensor or others designated to receive attribution as
provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not
licensed under this Public License, nor are publicity,
privacy, and/or other similar personality rights; however, to
the extent possible, the Licensor waives and/or agrees not to
assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed
Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this
Public License.
3. To the extent possible, the Licensor waives any right to
collect royalties from You for the exercise of the Licensed
Rights, whether directly or through a collecting society
under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly
reserves any right to collect such royalties.
Section 3 -- License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the
following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified
form), You must:
a. retain the following if it is supplied by the Licensor
with the Licensed Material:
i. identification of the creator(s) of the Licensed
Material and any others designated to receive
attribution, in any reasonable manner requested by
the Licensor (including by pseudonym if
designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of
warranties;
v. a URI or hyperlink to the Licensed Material to the
extent reasonably practicable;
b. indicate if You modified the Licensed Material and
retain an indication of any previous modifications; and
c. indicate the Licensed Material is licensed under this
Public License, and include the text of, or the URI or
hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any
reasonable manner based on the medium, means, and context in
which You Share the Licensed Material. For example, it may be
reasonable to satisfy the conditions by providing a URI or
hyperlink to a resource that includes the required
information.
3. If requested by the Licensor, You must remove any of the
information required by Section 3(a)(1)(A) to the extent
reasonably practicable.
b. ShareAlike.
In addition to the conditions in Section 3(a), if You Share
Adapted Material You produce, the following conditions also apply.
1. The Adapter's License You apply must be a Creative Commons
license with the same License Elements, this version or
later, or a BY-SA Compatible License.
2. You must include the text of, or the URI or hyperlink to, the
Adapter's License You apply. You may satisfy this condition
in any reasonable manner based on the medium, means, and
context in which You Share Adapted Material.
3. You may not offer or impose any additional or different terms
or conditions on, or apply any Effective Technological
Measures to, Adapted Material that restrict exercise of the
rights granted under the Adapter's License You apply.
Section 4 -- Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right
to extract, reuse, reproduce, and Share all or a substantial
portion of the contents of the database;
b. if You include all or a substantial portion of the database
contents in a database in which You have Sui Generis Database
Rights, then the database in which You have Sui Generis Database
Rights (but not its individual contents) is Adapted Material,
including for purposes of Section 3(b); and
c. You must comply with the conditions in Section 3(a) if You Share
all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.
Section 5 -- Disclaimer of Warranties and Limitation of Liability.
a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
c. The disclaimer of warranties and limitation of liability provided
above shall be interpreted in a manner that, to the extent
possible, most closely approximates an absolute disclaimer and
waiver of all liability.
Section 6 -- Term and Termination.
a. This Public License applies for the term of the Copyright and
Similar Rights licensed here. However, if You fail to comply with
this Public License, then Your rights under this Public License
terminate automatically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided
it is cured within 30 days of Your discovery of the
violation; or
2. upon express reinstatement by the Licensor.
For the avoidance of doubt, this Section 6(b) does not affect any
right the Licensor may have to seek remedies for Your violations
of this Public License.
c. For the avoidance of doubt, the Licensor may also offer the
Licensed Material under separate terms or conditions or stop
distributing the Licensed Material at any time; however, doing so
will not terminate this Public License.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
License.
Section 7 -- Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different
terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the
Licensed Material not stated herein are separate from and
independent of the terms and conditions of this Public License.
Section 8 -- Interpretation.
a. For the avoidance of doubt, this Public License does not, and
shall not be interpreted to, reduce, limit, restrict, or impose
conditions on any use of the Licensed Material that could lawfully
be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is
deemed unenforceable, it shall be automatically reformed to the
minimum extent necessary to make it enforceable. If the provision
cannot be reformed, it shall be severed from this Public License
without affecting the enforceability of the remaining terms and
conditions.
c. No term or condition of this Public License will be waived and no
failure to comply consented to unless expressly agreed to by the
Licensor.
d. Nothing in this Public License constitutes or may be interpreted
as a limitation upon, or waiver of, any privileges and immunities
that apply to the Licensor or You, including from the legal
processes of any jurisdiction or authority.
=======================================================================
Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.
Creative Commons may be contacted at creativecommons.org.

26
README.md Normal file
View File

@ -0,0 +1,26 @@
# Evolution Docs
Welcome to the EvolutionOS documentation. This repository contains the source data
behind <https://evolution-linux.github.io/wiki/>. Contributing to this repository follows
the same protocol as the packages tree. For details, please read
[CONTRIBUTING](./CONTRIBUTING.md).
## Building
The [res/build.sh](./res/build.sh) script builds HTML, roff and PDF versions of
the EvolutionOS documentation and the `evolution-docs.1` man page. It requires the following
EvolutionOS packages:
- `mdBook`
- `findutils` or `busybox + evolution-patches`
- `lowdown` (version 0.8.1 or greater)
- `texlive`
- `perl`
- `perl-File-Which`
- `perl-JSON`
- `librsvg-utils`
- `python3-md2gemini`
In order to build and install these files, set the `PREFIX` and `DESTDIR`
environment variables to appropriate values and run `res/build.sh` followed by
`res/install.sh`.

36
book.toml Normal file
View File

@ -0,0 +1,36 @@
[book]
authors = ["Tracker-Friendly"]
multilingual = false
src = "src"
title = "EvolutionOS Handbook"
[output.html]
theme = "src/theme"
[output.html.redirect]
"/about-this-handbook.html" = "/about/about-this-handbook.html"
"/config/man.html" = "/config/package-documentation/man.html"
"/config/gnupg.html" = "/config/openpgp.html#gnupg"
[output.latex]
optional = true
[output.gemini]
optional = true
[output.linkcheck]
optional = true
follow-web-links = true
exclude = [
'kernel\.org',
'ntp\.org',
'\.onion',
'localhost',
'userbase\.kde\.org',
'sjtu\.edu\.cn',
'mirrors\.cnnic\.cn',
'void\.webconverger\.org',
'mirror\.vofr\.net',
'void\.chililinux\.com',
'voidlinux\.com\.br',
]

71
check.sh Executable file
View File

@ -0,0 +1,71 @@
#!/bin/sh
# reset variable so it doesn't use the environment one
MISSING=
echo -n "Checking for mdbook-linkcheck ... "
if ! command -v mdbook-linkcheck; then
MISSING="$MISSING mdbook-linkcheck"
echo "not found"
fi
echo -n "Checking for vmdfmt ... "
if ! command -v vmdfmt; then
MISSING="$MISSING vmdfmt"
echo "not found"
fi
if [ "$MISSING" ]; then
echo -n "Checking for xbps-install ... "
if ! command -v xbps-install; then
echo "not found"
echo "Please manually install: $MISSING"
exit 1
fi
echo -n "Checking for sudo ... "
if command -v sudo; then
SU_CMD='sudo'
else
echo "not found"
echo "Checking for doas ... "
if command -v doas; then
SU_CMD='doas'
else
echo "not found"
"Please manually install: $MISSING"
exit 1
fi
fi
echo "\nTrying to install ${MISSING## } ... "
$SU_CMD xbps-install $MISSING
echo
# Check whether executables are now present.
for i in $MISSING; do
if ! command -v $i 2>&1 >/dev/null; then
UNAVAILABLE="$UNAVAILABLE $i"
fi
done
if [ "$UNAVAILABLE" ]; then
echo "Can't proceed without: ${UNAVAILABLE## }. Aborting."
exit 1
fi
fi
vmdfmt -l -w src/
if command -v mdbook 2>&1 >/dev/null; then
echo "Building book and checking links with mdbook ..."
mdbook build
else
echo "Checking links with mdbook-linkcheck ..."
mdbook-linkcheck -s
fi
echo "Checks completed."

2
res/README.md Normal file
View File

@ -0,0 +1,2 @@
The original cover variants, as suggested by @argosatcore on GitHub,
are available in the `handbook-cover-variants.svg` file.

92
res/build.sh Executable file
View File

@ -0,0 +1,92 @@
#!/bin/sh
# uses PREFIX and BUILD_MANPAGES from environment
: "${PREFIX:=/usr/local}"
: "${BUILD_MANPAGES:=1}"
set -e
PATH="$PWD/res:$PATH"
if [ -z "$SOURCE_DATE_EPOCH" ]; then
export SOURCE_DATE_EPOCH=$(git log --pretty='%ct' -1)
if [ -z "$SOURCE_DATE_EPOCH" -a "$BUILD_MANPAGES" = 1 ]; then
echo "git or SOURCE_DATE_EPOCH are needed to build man pages!"
exit 1
fi
fi
# Build HTML mdbook
echo "Building mdBook"
mdbook build
if [ "$BUILD_MANPAGES" = "1" ]; then
# Build mandoc version
echo "Building man pages"
cd src
find . -type d -exec mkdir -p "../mandoc/{}" \;
find . -type f -name "*.md" -exec sh -c \
'file="{}"; filew="${file%.md}"; \
man_date="$(git log --pretty=%cs -1 "$file" 2>/dev/null || date -d "@$SOURCE_DATE_EPOCH" +%F)";
lowdown -Tman \
${man_date:+-m "date: $man_date"} \
-m "title: ${filew##*/}" \
-m "section: 7" -m "source: Void Docs" -m "volume: Void Docs" \
-s -o "../mandoc/${filew}.7" "$file"' \;
cd -
fi
# Build script
echo "Building void-docs script and man page"
sed -e "s,@PREFIX@,$PREFIX," res/void-docs.in > res/void-docs
sed -e "s,@PREFIX@,$PREFIX," res/void-docs.1.in > res/void-docs.1
# Build PDF
echo "Building PDF"
## Temporarily add OpenType version of Latin Modern to font cache.
mkdir -p ~/.fonts
TMP_FONTDIR=$(mktemp -d -p ~/.fonts)
cp /usr/share/texmf-dist/fonts/opentype/public/lm/* $TMP_FONTDIR
fc-cache
## Create cover page using Latin Modern text.
rsvg-convert \
--dpi-x 300 \
--dpi-y 300 \
res/handbook-cover.svg > res/handbook-cover.png
## Letter version
pdflatex \
-output-directory=book/latex/ \
-jobname=handbook-letter \
book/latex/handbook.tex \
>/dev/null
pdflatex \
-output-directory=book/latex/ \
-jobname=handbook-letter \
book/latex/handbook.tex \
>/dev/null
## A4 version
sed -ie "s/\\documentclass\[letterpaper\]{article}/\\documentclass[a4paper]{article}/" \
book/latex/handbook.tex
pdflatex -output-directory=book/latex/ \
-jobname=handbook-a4 \
book/latex/handbook.tex \
>/dev/null
pdflatex -output-directory=book/latex/ \
-jobname=handbook-a4 \
book/latex/handbook.tex \
>/dev/null
## Remove temporary font directory
rm -rf $TMP_FONTDIR
fc-cache

22
res/ci/check-summary.sh Executable file
View File

@ -0,0 +1,22 @@
#!/bin/sh
ERROR=0
printf "\n\033[37;1m=> Checking SUMMARY.md\033[m\n"
cd src/ || exit 2
# summary is the list of files taken from SUMMARY.md - unused for now
summary="$( sed -e '/(/!d' -e 's/.*(//' -e 's/)//' ./SUMMARY.md )"
files="$( find . -type f -name '*.md' -not -name "SUMMARY.md" )"
for file in $files
do
if ! grep -q "$file" ./SUMMARY.md ; then
printf "::error title=Summary Lint,file=src/SUMMARY.md::$file not in SUMMARY.md\n"
ERROR=1
fi
done
exit $ERROR

46
res/ci/commit-lint.sh Executable file
View File

@ -0,0 +1,46 @@
#!/bin/sh
die() {
printf '%s\n' "$*" >&2
exit 1
}
command -v git >/dev/null 2>&1 ||
die "neither chroot-git nor git could be found!"
tip="$(git rev-list -1 --parents HEAD)"
case "$tip" in
# This is a merge commit, pick last parent
*" "*" "*) tip="${tip##* }" ;;
# This is a non-merge commit, pick itself
*) tip="${tip%% *}" ;;
esac
base="$(git merge-base origin/HEAD "$tip")"
[ $(git rev-list --count "$tip" "^$base") -lt 20 ] || {
echo "::error title=Branch out of date::Your branch is too out of date. Please rebase on upstream and force-push."
exit 1
}
status=0
for cmt in $(git rev-list --abbrev-commit $base..$tip)
do
git cat-file commit "$cmt" |
awk -vC="$cmt" '
# skip header
/^$/ && !msg { msg = 1; next }
!msg { next }
# 3: long-line-is-banned-except-footnote-like-this-for-url
(NF > 2) && (length > 80) { print "::error title=Commit Lint::" C ": long line: " $0; exit 1 }
!subject {
if (length > 50) { print "::warning title=Commit Lint::" C ": subject is a bit long" }
if (!($0 ~ ":")) { print "::error title=Commit Lint::" C ": subject does not follow CONTRIBUTING.md guidelines"; exit 1 }
subject = 1; next
}
/^$/ { body = 1; next }
!body { print "::error title=Commit Lint::" C ": second line must be blank"; exit 1 }
' || status=1
done
exit $status

15
res/ci/format.sh Executable file
View File

@ -0,0 +1,15 @@
#!/bin/sh
printf "\n\033[37;1m=> Formatting tree\033[m\n"
vmdfmt -l -w src/
# Check Status
if [ ! -z "$(git status --porcelain)" ] ; then
git diff --color=always
printf "\033[31;1m=> Files which need to be formatted:\033[m\n"
for f in $(git status | grep -Po 'modified:\K.*$'); do
printf "$f\n"
printf "::error title=Formatting Lint,file=$f,line=1::File has improper formatting\n"
done
exit 1
fi

11
res/ci/linkcheck.sh Executable file
View File

@ -0,0 +1,11 @@
#!/bin/sh
# only show all the debug messages if ci is run with debug
if [ "$RUNNER_DEBUG" ]; then
loglevel=debug
else
loglevel=error
fi
printf "\033[37;1m=> Checking links\033[m\n"
RUST_LOG="linkcheck=$loglevel" mdbook-linkcheck -s -c always

1121
res/handbook-cover-variants.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 219 KiB

502
res/handbook-cover.svg Normal file
View File

@ -0,0 +1,502 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
id="svg-cover_page"
version="1.1"
viewBox="0 0 160 230"
height="230mm"
width="160mm"
sodipodi:docname="handbook-cover.svg"
inkscape:version="1.2.2 (b0a8486541, 2022-12-01)"
xml:space="preserve"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"><defs
id="defs512"><rect
x="206.62163"
y="735.32098"
width="386.4261"
height="129.66423"
id="rect1641" /><rect
x="209.59138"
y="735.16314"
width="383.1422"
height="124.70311"
id="rect1635" /><rect
x="688.45399"
y="840.28597"
width="439.67783"
height="92.200577"
id="rect1629" /><rect
x="691.20444"
y="854.46835"
width="124.00641"
height="93.684849"
id="rect1623" /><rect
x="706.27132"
y="866.46369"
width="-127.88976"
height="205.7141"
id="rect1617" /></defs><sodipodi:namedview
id="namedview510"
pagecolor="#ffffff"
bordercolor="#000000"
borderopacity="0.25"
inkscape:showpageshadow="2"
inkscape:pageopacity="0.0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#d1d1d1"
inkscape:document-units="mm"
showgrid="false"
inkscape:zoom="10.837512"
inkscape:cx="462.42161"
inkscape:cy="295.6398"
inkscape:window-width="1432"
inkscape:window-height="831"
inkscape:window-x="0"
inkscape:window-y="0"
inkscape:window-maximized="1"
inkscape:current-layer="g-content" /><metadata
id="metadata-cover_page"><rdf:RDF><cc:Work
rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" /><dc:title /></cc:Work></rdf:RDF></metadata><g
id="g-page"><rect
style="fill:#ffffff;"
id="rect-page"
width="160"
height="230"
x="0"
y="0" /></g><g
id="g-content"><path
style="stroke:#000000;stroke-width:0.5;stroke-opacity:1"
d="M 52,229 V 194.45232"
id="path-vertical_divider" /><text
id="text-title"
transform="translate(-36.36392,-6.1088655)"
style="font-size:6px;line-height:1.25;font-family:'Latin Modern Roman';white-space:pre;inline-size:60.3944;display:inline"
xml:space="preserve"
x="44"
y="216"><tspan
x="44"
y="216"
id="tspan2077">EvolutionOS </tspan><tspan
x="44"
y="223.5"
id="tspan2079">Handbook</tspan></text><text
id="text-blurb"
style="font-size:4.2px;line-height:1.05;font-family:'Latin Modern Roman'"
transform="translate(-1.6329418,-11.49269)" /><image
preserveAspectRatio="none"
inkscape:svg-dpi="96"
width="74.055511"
height="73.131363"
xlink:href="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+Cjxz
dmcKICAgd2lkdGg9IjI1NiIKICAgaGVpZ2h0PSIyNTYiCiAgIHZpZXdCb3g9IjAgMCAyNTIuMDYx
NTQgMjUyLjA2MTUzIgogICB2ZXJzaW9uPSIxLjEiCiAgIHByZXNlcnZlQXNwZWN0UmF0aW89InhN
aWRZTWlkIgogICBpZD0idm9pZGxvZ28iCiAgIHNvZGlwb2RpOmRvY25hbWU9ImV2b2x1dGlvbi1s
b2dvLnN2ZyIKICAgaW5rc2NhcGU6dmVyc2lvbj0iMS4yLjIgKGIwYTg0ODY1NDEsIDIwMjItMTIt
MDEpIgogICB4bWxuczppbmtzY2FwZT0iaHR0cDovL3d3dy5pbmtzY2FwZS5vcmcvbmFtZXNwYWNl
cy9pbmtzY2FwZSIKICAgeG1sbnM6c29kaXBvZGk9Imh0dHA6Ly9zb2RpcG9kaS5zb3VyY2Vmb3Jn
ZS5uZXQvRFREL3NvZGlwb2RpLTAuZHRkIgogICB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAw
MC9zdmciCiAgIHhtbG5zOnN2Zz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxzb2Rp
cG9kaTpuYW1lZHZpZXcKICAgICBpZD0ibmFtZWR2aWV3NTgwIgogICAgIHBhZ2Vjb2xvcj0iI2Zm
ZmZmZiIKICAgICBib3JkZXJjb2xvcj0iIzAwMDAwMCIKICAgICBib3JkZXJvcGFjaXR5PSIwLjI1
IgogICAgIGlua3NjYXBlOnNob3dwYWdlc2hhZG93PSIyIgogICAgIGlua3NjYXBlOnBhZ2VvcGFj
aXR5PSIwLjAiCiAgICAgaW5rc2NhcGU6cGFnZWNoZWNrZXJib2FyZD0iMCIKICAgICBpbmtzY2Fw
ZTpkZXNrY29sb3I9IiNkMWQxZDEiCiAgICAgc2hvd2dyaWQ9ImZhbHNlIgogICAgIGlua3NjYXBl
Onpvb209IjEuMjM1NDgyNCIKICAgICBpbmtzY2FwZTpjeD0iLTYwLjMwMDMzMyIKICAgICBpbmtz
Y2FwZTpjeT0iMTQ2LjUwMTQ4IgogICAgIGlua3NjYXBlOndpbmRvdy13aWR0aD0iMTQzMiIKICAg
ICBpbmtzY2FwZTp3aW5kb3ctaGVpZ2h0PSI4MzEiCiAgICAgaW5rc2NhcGU6d2luZG93LXg9IjAi
CiAgICAgaW5rc2NhcGU6d2luZG93LXk9IjAiCiAgICAgaW5rc2NhcGU6d2luZG93LW1heGltaXpl
ZD0iMSIKICAgICBpbmtzY2FwZTpjdXJyZW50LWxheWVyPSJ2b2lkbG9nbyIgLz4KICA8ZGVmcwog
ICAgIGlkPSJkZWZzNTY2IiAvPgogIDxnCiAgICAgaWQ9Imw0Y1ZUVDZ6NVhIeEVySzc4a2xlNE5t
IgogICAgIGZpbGw9IiNiN2I3YjciCiAgICAgdHJhbnNmb3JtPSJtYXRyaXgoMC4wMjI1MDE4LDAs
MCwwLjAyMjUwMTgsLTgwLjQwNzA3OSwzLjIzMTY1NzYpIj4KICAgIDxnCiAgICAgICBpZD0iZzI2
NiI+CiAgICAgIDxwYXRoCiAgICAgICAgIGlkPSJwMURpSFlEb0NxIgogICAgICAgICBkPSJNIDgy
NDAsMTA3ODAgQyA3MjA5LDEwNjIzIDYzMTgsMTAyMjQgNTUyMCw5NTYwIDUzNTksOTQyNiA1MDE0
LDkwODEgNDg4MCw4OTIwIDQxMzQsODAyMiAzNzA5LDY5NzcgMzYyMCw1ODIxIGMgLTEzLC0xNzMg
LTEzLC01ODkgMCwtNzYyIDg5LC0xMTU2IDUxNCwtMjIwMSAxMjYwLC0zMDk5IDEzNCwtMTYxIDQ3
OSwtNTA2IDY0MCwtNjQwIEMgNjQwMiw1ODcgNzQxNSwxNjggODU1NSw2NSBjIDk0LC04IDIwNCwt
MTkgMjQ1LC0yNCA0MSwtNSAxNDUsLTE1IDIzMSwtMjEgMzY4LC0yOCAxMDA0LDU4IDE0OTQsMjAx
IDEwMSwzMCA0MjMsMTM4IDQ3MCwxNTkgODQsMzYgMTkxLDgyIDIxMCw4OSAxMSw1IDU3LDI3IDEw
Miw1MCA0NCwyMiA4OCw0MSA5Nyw0MSA5LDAgMTYsNSAxNiwxMCAwLDYgOSwxMCAyMCwxMCAxMSww
IDIwLDUgMjAsMTAgMCw2IDksMTAgMjAsMTAgMTEsMCAyMCwzIDIwLDggMCw0IDE0LDE0IDMyLDIx
IDE4LDggNzgsNDEgMTM0LDczIDU1LDMyIDEwNiw1OCAxMTMsNTggNiwwIDExLDQgMTEsMTAgMCw1
IDExLDEyIDI1LDE2IDE0LDMgMjUsOSAyNSwxMyAwLDQgMTIsMTQgMjgsMjIgMTUsOCA3NSw0NyAx
MzMsODYgNTksNDAgMTA5LDczIDExMiw3MyAzLDAgMTgsMTEgMzMsMjUgMTUsMTQgMzMsMjUgNDAs
MjUgNywwIDE3LDYgMjEsMTQgNCw3IDI2LDI1IDQ4LDM4IDIyLDE0IDUwLDM1IDYyLDQ3IDEyLDEy
IDI2LDIxIDMwLDIxIDQsMCAyOCwxOCA1Miw0MCAyNSwyMiA0Nyw0MCA1MCw0MCAzLDAgMzEsMjMg
NjEsNTAgMzAsMjcgNzcsNjkgMTA0LDkyIDc1LDY2IDQwNCwzOTUgNDY2LDQ2NyAzMCwzNSA2MCw2
OSA2NSw3NSA2LDYgMjYsMzEgNDUsNTYgMzMsNDIgNTAsNjIgODUsMTAxIDgsOSAxNSwxOSAxNSwy
NCAwLDUgNywxNSAxNSwyNCAzNSwzNiAxMTgsMTQ2IDEyNiwxNjggNSwxMyAxMywyMyAxOSwyMyA1
LDAgMTAsNyAxMCwxNSAwLDggNSwxNSAxMCwxNSA2LDAgMTAsNyAxMCwxNSAwLDggNCwxNSA4LDE1
IDUsMCAxNSwxMiAyMywyOCA4LDE1IDE3LDI5IDIwLDMyIDIxLDE3IDIwNCwzMjEgMjYyLDQzNSAx
NDMsMjg0IDE4MiwzNjggMjYwLDU2NiA0NjgsMTE4NCA1MDMsMjUzMiA5NywzNzQ5IC0yMTcsNjUx
IC01NDAsMTIyOCAtOTkwLDE3NzAgLTEzNCwxNjEgLTQ4OSw1MTYgLTY1MCw2NTAgLTUzNyw0NDYg
LTExMTQsNzcwIC0xNzU1LDk4NSAtMzQzLDExNiAtNTA5LDE1MCAtOTEwLDE5MiAtMTQwLDE0IC0y
ODQsMTggLTgyNSwxOSAtNjAwLDIgLTY2NiwxIC03ODAsLTE2IHogbSAxMTYwLC00MzAgYyA3MTcs
LTM3IDEzNTEsLTE5OCAxOTg1LC01MDUgNTE4LC0yNTAgOTc5LC01NzggMTM5MSwtOTg5IDExNzcs
LTExNzggMTcwNCwtMjgzMCAxNDI4LC00NDgxIC0xMzAsLTc3OSAtNDU3LC0xNTQzIC05MzksLTIx
OTAgLTI2OSwtMzYyIC02MjMsLTcyNCAtOTczLC05OTQgLTExNCwtODkgLTM4MSwtMjc2IC00MTIs
LTI5MCAtOCwtMyAtNDEsLTIzIC03MiwtNDQgLTMyLC0yMCAtNjgsLTQyIC04MCwtNDggLTEzLC01
IC00MSwtMjEgLTYzLC0zNCAtMjIsLTE0IC03MSwtNDAgLTExMCwtNjAgLTM4LC0xOSAtODQsLTQ0
IC0xMDIsLTU1IC0xNywtMTIgLTQxLC0yMyAtNTMsLTI1IC0xMiwtMiAtNTAsLTIwIC04NiwtNDAg
LTM1LC0yMCAtNjQsLTMzIC02NCwtMzAgMCw0IC0yMCwtNSAtNDUsLTE5IC0yNSwtMTUgLTQ1LC0y
NCAtNDUsLTIxIDAsNCAtMTYsLTMgLTM1LC0xNSAtMTksLTEyIC0zNSwtMTkgLTM1LC0xNiAwLDQg
LTExLC0xIC0yNSwtMTAgLTE0LC05IC0yNSwtMTMgLTI1LC0xMCAwLDQgLTExLC0xIC0yNSwtMTAg
LTE0LC05IC0yNSwtMTMgLTI1LC05IDAsNCAtNywyIC0xNSwtNSAtOCwtNyAtMTUsLTkgLTE1LC02
IDAsNCAtMTAsMSAtMjIsLTYgLTEzLC03IC0yNiwtMTMgLTMwLC0xNCAtNSwtMSAtMTAsLTMgLTEz
LC00IC0zLC0xIC05LC00IC0xNSwtNSAtNSwtMSAtMTIsLTQgLTE1LC01IC0zLC0xIC05LC00IC0x
NSwtNSAtNSwtMSAtMTEsLTMgLTEyLC01IC0yLC0xIC0xMSwtMyAtMjAsLTUgLTMzLC02IC05Mywt
MjggLTEwNSwtMzggLTcsLTUgLTEzLC02IC0xMywtMiAwLDQgLTcsMiAtMTUsLTUgLTgsLTcgLTE1
LC05IC0xNSwtNSAwLDQgLTcsMiAtMTUsLTUgLTgsLTcgLTE1LC05IC0xNSwtNSAwLDQgLTYsMiAt
MTMsLTQgLTgsLTYgLTE3LC04IC0yMCwtNCAtNCwzIC0xMywwIC0yMiwtNyAtOCwtNyAtMTUsLTkg
LTE1LC01IDAsNCAtNiwyIC0xMywtNCAtOCwtNiAtMTcsLTggLTIwLC00IC00LDMgLTEzLDAgLTIy
LC03IC04LC03IC0xNSwtOSAtMTUsLTQgMCw0IC01LDMgLTExLC0zIC02LC02IC0xNywtOSAtMjQs
LTcgLTcsMyAtMTYsMSAtMTksLTUgLTQsLTYgLTEzLC04IC0yMCwtNSAtOCwzIC0xNywxIC0yMCwt
NSAtNCwtNiAtMTMsLTggLTIwLC01IC04LDMgLTE3LDEgLTIwLC01IC00LC02IC0xMywtOCAtMjAs
LTUgLTgsMyAtMTcsMSAtMjAsLTQgLTMsLTYgLTE1LC04IC0yNSwtNSAtMTAsMyAtMjIsMCAtMjUs
LTYgLTQsLTUgLTEzLC04IC0yMCwtNSAtOCwzIC0xNywxIC0yMCwtNCAtMywtNiAtMTUsLTggLTI1
LC01IC0xMCwzIC0yMiwwIC0yNSwtNSAtMywtNiAtMTUsLTggLTI1LC01IC0xMCwzIC0yMiwwIC0y
NSwtNSAtMywtNiAtMTUsLTggLTI1LC01IC0xMCwzIC0yMiwwIC0yNSwtNiAtNCwtNiAtMTgsLTgg
LTMxLC01IC0xMiwzIC0yNiwxIC0yOSwtNCAtMywtNiAtMTUsLTggLTI2LC01IC0xMSwzIC0yNiww
IC0zNCwtNiAtNywtNiAtMjEsLTkgLTMwLC01IC05LDMgLTI0LDMgLTMzLC0xIC0xMCwtNCAtMzAs
LTcgLTQ1LC02IC0xNCwxIC0yOSwtMiAtMzIsLTggLTQsLTUgLTIxLC03IC00MCwtNCAtMTgsMyAt
MzYsMSAtNDAsLTUgLTMsLTYgLTIzLC04IC00NSwtNSAtMjIsMyAtNDEsMSAtNDUsLTUgLTQsLTYg
LTI3LC04IC02MCwtNSAtMzIsMyAtNTYsMSAtNjAsLTUgLTQsLTcgLTMzLC04IC04MCwtNSAtNDEs
MyAtODMsMiAtOTMsLTIgLTI3LC0xMSAtNDEzLC0xMiAtNDEzLC0xIDAsNSAtMzcsNiAtOTAsMyAt
NjMsLTUgLTkwLC0zIC05MCw0IDAsOCAtMTgsMTAgLTYwLDUgLTQzLC01IC02MCwtNCAtNjAsNSAw
LDggLTE0LDkgLTQ1LDUgLTMxLC01IC00NSwtNCAtNDUsNCAwLDggLTEzLDEwIC00MCw1IC0yOCwt
NSAtNDAsLTMgLTQwLDUgMCw5IC0xMSwxMCAtMzUsNiAtMjMsLTUgLTM1LC0zIC0zNSw0IDAsNyAt
MTIsOSAtMzUsNCAtMjQsLTQgLTM1LC0zIC0zNSw2IDAsOCAtMTAsOSAtMzAsNSAtMTksLTQgLTMw
LC0zIC0zMCw0IDAsNiAtMTIsOCAtMzAsNSAtMTksLTQgLTMwLC0yIC0zMCw1IDAsNyAtOSw5IC0y
NSw1IC0xNiwtNCAtMjUsLTIgLTI1LDUgMCw3IC05LDkgLTI1LDUgLTE2LC00IC0yNSwtMiAtMjUs
NSAwLDcgLTksOSAtMjUsNSAtMTQsLTMgLTI1LC0yIC0yNSw0IDAsNiAtOSw4IC0yMCw1IC0xMSwt
MyAtMjAsMCAtMjAsNiAwLDcgLTksOSAtMjUsNSAtMTQsLTMgLTI1LC0yIC0yNSw0IDAsNiAtOSw4
IC0yMCw1IC0xMSwtMyAtMjAsLTEgLTIwLDUgMCw2IC05LDggLTIwLDUgLTExLC0zIC0yMCwtMSAt
MjAsNSAwLDYgLTksOCAtMjAsNSAtMTEsLTMgLTIwLC0xIC0yMCwzIDAsNSAtMTQsMTAgLTMxLDEw
IC0xNywxIC0zNCw1IC0zOCwxMCAtMyw1IC0xOSwxMCAtMzYsMTEgLTE2LDEgLTMxLDcgLTMzLDEz
IC0yLDUgLTgsOCAtMTMsNCAtMTEsLTYgLTExMSwyNSAtMTE5LDM3IC04LDExIC04NywzOSAtOTMs
MzIgLTksLTggLTExMSwyOSAtMTIwLDQzIC00LDcgLTEzLDExIC0yMSw4IC0xNywtNiAtMTY5LDU0
IC0xNzgsNzEgLTUsNyAtMTYsMTEgLTI2LDggLTEwLC0yIC0yOSw3IC00NiwyMiAtMTUsMTQgLTMy
LDIzIC0zNywxOSAtMTIsLTcgLTY5LDE1IC02OSwyNyAwLDEyIC03Niw1MCAtODQsNDIgLTgsLTkg
LTg3LDI4IC04MCwzOCA1LDkgLTY3LDQ5IC05MCw0OSAtMjQsMCAtNjYsMjIgLTYwLDMyIDYsOSAt
MiwxMiAtNDksMjIgLTE1LDQgLTI1LDExIC0yMiwxNiA2LDEwIC0xLDE0IC00OCwyNCAtMTUsNCAt
MjUsMTAgLTIzLDE1IDMsNSAtOCwxMSAtMjUsMTUgLTE3LDMgLTI4LDEwIC0yNCwxNiAzLDUgLTMs
MTAgLTE0LDEwIC0xMiwwIC0yMCw2IC0xOSwxMyAyLDcgLTksMTMgLTI1LDE1IC0xNSwyIC0yNSw4
IC0yMiwxMyA0LDUgLTMsOSAtMTUsOSAtMTIsMCAtMTgsNSAtMTUsMTAgMyw2IC0zLDEwIC0xNSwx
MCAtMTIsMCAtMTgsNSAtMTUsMTAgMyw2IC0zLDEwIC0xNSwxMCAtMTIsMCAtMTgsNCAtMTUsMTAg
Myw1IC0zLDEwIC0xNSwxMCAtMTIsMCAtMTgsNCAtMTUsMTAgMyw1IC0zLDEwIC0xNSwxMCAtMTIs
MCAtMTgsNSAtMTUsMTAgMyw2IC0zLDEwIC0xNSwxMCAtMTIsMCAtMTgsNSAtMTUsMTAgMyw2IC0z
LDEwIC0xNCwxMCAtMTIsMCAtMjEsNyAtMjEsMTUgMCw4IC05LDE1IC0yMSwxNSAtMTEsMCAtMTcs
NSAtMTQsMTAgMyw2IC0zLDEwIC0xNCwxMCAtMTIsMCAtMjAsNiAtMTksMTIgMiw3IC03LDE0IC0x
OSwxNiAtMTMsMiAtMjMsMTAgLTIzLDE4IDAsOCAtOSwxNCAtMjAsMTQgLTExLDAgLTIwLDYgLTIw
LDE0IDAsOCAtMTAsMTYgLTIyLDE4IC0xMywyIC0yMywxMCAtMjMsMTggMCw4IC0xMCwxNiAtMjMs
MTggLTEyLDIgLTIwLDcgLTE3LDEyIDYsMTAgLTE0LDI3IC00MCwzMiAtMTEsMiAtMjAsMTAgLTIw
LDE4IDAsOCAtOSwxNiAtMjAsMTggLTI1LDUgLTQ2LDIyIC00MCwzMiA2LDEwIC0xNSwyNyAtMzks
MzEgLTExLDIgLTI3LDE3IC0zNiwzMyAtOCwxNiAtMjMsMzMgLTMzLDM4IC05LDQgLTI1LDEyIC0z
NCwxNiAtMTAsNSAtMjMsMTkgLTMwLDMyIC0xNCwyOCAtMjU0LDI3MCAtMjY3LDI3MCAtMTYsMCAt
NDUsMzEgLTQwLDQ0IDUsMTMgLTIzLDQzIC01OSw2MCAtMTIsNyAtMjIsMjAgLTIyLDMwIDAsMTEg
LTEzLDI3IC0zMCwzNiAtMTgsMTAgLTI5LDI0IC0yNywzNCAyLDEwIC02LDIwIC0yMCwyNSAtMTMs
NCAtMjMsMTcgLTIzLDI3IDAsMTAgLTksMjMgLTIxLDI5IC0xMSw1IC0xOSwxNiAtMTYsMjMgMiw2
IC04LDE2IC0yMiwyMiAtMTgsNiAtMjQsMTQgLTIwLDI1IDUsMTEgMCwxOCAtMTQsMjIgLTEzLDMg
LTE5LDEwIC0xNSwyMCA0LDkgLTIsMTYgLTE1LDIwIC0xMywzIC0xOSwxMCAtMTUsMjAgNCw5IC0y
LDE2IC0xNSwyMCAtMTMsMyAtMTksMTAgLTE1LDE5IDMsOCAtMSwxNCAtMTEsMTQgLTEwLDAgLTEz
LDYgLTksMTYgNCwxMCAtMSwxNyAtMTUsMjEgLTEzLDMgLTE5LDEwIC0xNSwxOSAzLDggLTEsMTQg
LTExLDE0IC0xMCwwIC0xMyw2IC0xMCwxNSA0LDkgMCwxNSAtMTAsMTUgLTEwLDAgLTEzLDYgLTEw
LDE1IDQsOSAwLDE1IC0xMCwxNSAtMTAsMCAtMTMsNiAtMTAsMTUgNCw5IDAsMTUgLTEwLDE1IC0x
MCwwIC0xMyw2IC0xMCwxNSA0LDkgMCwxNSAtMTAsMTUgLTEwLDAgLTEzLDYgLTEwLDE1IDQsOSAw
LDE1IC0xMCwxNSAtMTAsMCAtMTMsNiAtMTAsMTUgNCwxMCAwLDE1IC0xMSwxNSAtOSwwIC0xNCw0
IC0xMSw5IDksMTQgLTQsNDEgLTIwLDQxIC04LDAgLTExLDYgLTgsMTUgNCwxMCAwLDE1IC0xMSwx
NSAtOSwwIC0xMyw1IC0xMCwxMCAzLDYgMiwxMCAtNCwxMCAtNiwwIC04LDcgLTUsMTUgNCwxMCAw
LDE1IC0xMSwxNSAtOSwwIC0xMyw0IC0xMCwxMCAzLDUgMSwxMCAtNSwxMCAtNiwwIC05LDQgLTYs
OSA5LDE0IC01LDQxIC0yMSw0MSAtOCwwIC0xMSw0IC04LDEwIDMsNSAxLDEwIC01LDEwIC02LDAg
LTksNCAtNiw5IDksMTQgLTUsNDEgLTIxLDQxIC04LDAgLTExLDUgLTgsMTAgMyw1IDEsMTAgLTUs
MTAgLTYsMCAtOCw0IC01LDEwIDMsNSAxLDEwIC01LDEwIC02LDAgLTksNCAtNSw5IDgsMTQgLTM3
LDEwMSAtNTMsMTAxIC03LDAgLTEwLDQgLTcsMTAgMyw1IDEsMTAgLTUsMTAgLTYsMCAtOCw1IC01
LDEwIDMsNiAxLDEwIC01LDEwIC02LDAgLTgsNSAtNSwxMCAzLDYgMiwxMCAtNCwxMCAtNiwwIC04
LDYgLTUsMTQgNiwxNyAtMzIsOTYgLTQ3LDk2IC02LDAgLTcsNCAtNCwxMCAzLDUgMSwxMCAtNSwx
MCAtNiwwIC04LDUgLTUsMTAgMyw2IDIsMTAgLTMsMTAgLTYsMCAtOCw5IC01LDE5IDMsMTEgLTMs
MjcgLTE1LDM5IC0xMSwxMSAtMTgsMjMgLTE1LDI2IDQsMyAyLDYgLTQsNiAtNiwwIC05LDkgLTYs
MjAgMywxMiAtMSwyMiAtMTEsMjYgLTksMyAtMTMsMTAgLTEwLDE1IDMsNSAxLDkgLTUsOSAtNiww
IC04LDcgLTUsMTUgNCw4IDEsMTUgLTYsMTUgLTYsMCAtOCw1IC01LDEwIDMsNiAyLDEwIC00LDEw
IC02LDAgLTgsNyAtNSwxNSA0LDggMSwxNSAtNiwxNSAtNiwwIC04LDUgLTUsMTAgMyw2IDIsMTAg
LTQsMTAgLTYsMCAtOCw3IC01LDE1IDQsOCAyLDE1IC00LDE1IC02LDAgLTgsOSAtNSwyMCAzLDEy
IC0xLDIyIC0xMCwyNiAtOSwzIC0xMywxMiAtMTAsMjAgMyw4IDAsMTQgLTYsMTQgLTYsMCAtOCw3
IC01LDE1IDQsOCAxLDE1IC01LDE1IC02LDAgLTgsNyAtNSwxNSA0LDggMSwxNSAtNiwxNSAtNiww
IC04LDUgLTUsMTAgOCwxMyAtMjMsMTEwIC0zNSwxMTAgLTUsMCAtNyw3IC00LDE1IDQsOCAxLDE1
IC01LDE1IC02LDAgLTgsNyAtNSwxNSA0LDggMSwxNSAtNSwxNSAtNiwwIC04LDcgLTUsMTUgNCw4
IDIsMTUgLTQsMTUgLTYsMCAtOCw5IC01LDIwIDMsMTEgMCwyMCAtNiwyMCAtNSwwIC04LDcgLTUs
MTUgNCw4IDIsMTUgLTQsMTUgLTYsMCAtOCw5IC01LDIwIDMsMTEgMCwyMCAtNiwyMCAtNSwwIC04
LDcgLTUsMTUgNCw4IDIsMTUgLTQsMTUgLTYsMCAtOCw5IC01LDIwIDMsMTEgMSwyMCAtNSwyMCAt
NiwwIC04LDkgLTUsMjAgMywxMSAxLDIwIC01LDIwIC02LDAgLTgsOSAtNSwyMCAzLDExIDEsMjAg
LTUsMjAgLTYsMCAtOCw5IC01LDIwIDMsMTEgMSwyMCAtNCwyMCAtNiwwIC04LDExIC01LDI1IDIs
MTQgMCwyNSAtNiwyNSAtNiwwIC04LDkgLTUsMjAgMywxMSAxLDIwIC00LDIwIC02LDAgLTgsMTEg
LTUsMjUgMiwxNCAwLDI1IC01LDI1IC02LDAgLTgsMTEgLTUsMjUgMiwxNCAwLDI1IC01LDI1IC02
LDAgLTgsMTEgLTUsMjUgMiwxNCAwLDI1IC03LDI1IC02LDAgLTgsMTEgLTUsMzAgNCwxNyAyLDMw
IC0zLDMwIC01LDAgLTgsMTMgLTUsMzAgMiwxNyAwLDMwIC02LDMwIC03LDAgLTksMTQgLTUsMzUg
MywxOSAxLDM1IC00LDM1IC01LDAgLTcsMTYgLTUsMzUgMiwyMCAwLDM1IC02LDM1IC02LDAgLTgs
MTYgLTUsNDAgMywyNCAyLDQwIC00LDQwIC02LDAgLTksMTggLTUsNDUgMywyOCAxLDQ1IC02LDQ1
IC02LDAgLTgsMjIgLTUsNjAgNCwzNyAyLDYwIC00LDYwIC03LDAgLTksMzMgLTUsOTAgMiw1MCAx
LDkwIC00LDkwIC01LDAgLTksOTAgLTksMjAwIDAsMTEwIDQsMjAwIDksMjAwIDUsMCA2LDQwIDQs
OTAgLTMsNTUgLTIsOTMgNCw5NiA2LDQgOCwzMSA2LDYwIC0zLDMxIC0xLDU0IDUsNTQgNSwwIDcs
MTkgNSw0NSAtNCwyNyAtMSw0NSA1LDQ1IDYsMCA3LDE2IDQsNDAgLTMsMjQgLTEsNDAgNSw0MCA2
LDAgOCwxNSA2LDM1IC0yLDE5IDAsMzUgNSwzNSA1LDAgNywxNiA0LDM1IC00LDIxIC0yLDM1IDUs
MzUgNiwwIDgsMTMgNiwzMCAtMywxNyAwLDMwIDUsMzAgNSwwIDcsMTMgNCwzMCAtNCwxOSAtMiwz
MCA0LDMwIDcsMCA5LDExIDcsMjUgLTMsMTQgLTEsMjUgNSwyNSA1LDAgNywxMSA1LDI1IC0zLDE0
IC0xLDI1IDUsMjUgNSwwIDcsMTEgNSwyNSAtMywxNCAtMSwyNSA1LDI1IDUsMCA3LDkgNCwyMCAt
MywxMSAtMSwyMCA1LDIwIDYsMCA4LDExIDYsMjUgLTMsMTQgLTEsMjUgNSwyNSA1LDAgNyw5IDQs
MjAgLTMsMTEgLTEsMjAgNSwyMCA2LDAgOCw5IDUsMjAgLTMsMTEgLTEsMjAgNSwyMCA2LDAgOCw5
IDUsMjAgLTMsMTEgLTEsMjAgNSwyMCA2LDAgOCw5IDUsMjAgLTMsMTEgLTEsMjAgNSwyMCA2LDAg
OCw3IDQsMTUgLTMsOCAwLDE1IDUsMTUgNiwwIDksOSA2LDIwIC0zLDExIC0xLDIwIDUsMjAgNiww
IDgsNyA0LDE1IC0zLDggMCwxNSA1LDE1IDYsMCA5LDkgNiwyMCAtMywxMSAtMSwyMCA1LDIwIDYs
MCA4LDcgNCwxNSAtMyw4IC0xLDE1IDUsMTUgNiwwIDksNyA1LDE1IC0zLDggLTEsMTUgNSwxNSA2
LDAgOSw3IDUsMTUgLTMsOCAtMiwxNSAyLDE1IDgsMCAzOCw5OSAzNCwxMTMgLTEsNCAzLDcgOSw3
IDYsMCA5LDcgNSwxNSAtMyw4IC0xLDE1IDUsMTUgNiwwIDksNyA1LDE1IC0zLDggLTEsMTUgNSwx
NSA2LDAgOSw2IDYsMTQgLTMsOCAtMSwxNiA0LDE4IDUsMiAxMSwxMyAxMiwyNiAwLDEyIDUsMjIg
MTAsMjIgNSwwIDcsNiA0LDE0IC0zLDggLTIsMTYgMywxOCA0LDIgMTAsMTIgMTIsMjMgMSwxMSA2
LDIyIDEwLDI1IDMsMyA4LDE0IDEwLDI1IDEsMTEgOSwyNiAxNiwzMyAxMSwxMiAxNiwzNCAxMyw1
NSAwLDQgMyw3IDgsNyAxMCwwIDM3LDY5IDMzLDgzIC0xLDQgMyw3IDksNyA1LDAgNyw1IDQsMTAg
LTMsNiAtMiwxMCAzLDEwIDksMCA1OCwxMTAgNTQsMTIzIC0xLDQgMyw3IDksNyA1LDAgNyw1IDQs
MTAgLTMsNiAtMSwxMCA1LDEwIDYsMCA4LDUgNSwxMCAtMyw2IC0xLDEwIDUsMTAgNiwwIDgsNSA1
LDEwIC0zLDYgLTIsMTAgMywxMCA1LDAgMTksMjQgMzMsNTMgMTMsMjggMzAsNTggMzcsNjUgNyw4
IDEwLDE4IDcsMjMgLTQsNSAtMiw5IDQsOSA2LDAgMTMsMTEgMTcsMjUgMywxNCAxMCwyNSAxNiwy
NSA1LDAgNiw1IDMsMTAgLTMsNiAtMiwxMCA0LDEwIDYsMCAxMywxMSAxNywyNSAzLDE0IDExLDI1
IDE3LDI1IDYsMCA4LDMgNCw2IC0zLDMgMywxNSAxMywyNyAxMSwxMSAxNywyNCAxNCwyOSAtMyw0
IDAsOCA1LDggNiwwIDExLDcgMTEsMTUgMCw4IDQsMTUgMTAsMTUgNSwwIDEyLDExIDE2LDI1IDMs
MTQgMTAsMjUgMTUsMjUgNSwwIDksNyA5LDE1IDAsOCA1LDE1IDEwLDE1IDYsMCAxMCw3IDEwLDE1
IDAsOCA1LDE1IDEwLDE1IDYsMCAxMCw3IDEwLDE1IDAsOCA1LDE1IDEwLDE1IDYsMCAxMCw3IDEw
LDE1IDAsOCA1LDE1IDEwLDE1IDYsMCAxMCw3IDEwLDE1IDAsOCA1LDE1IDEwLDE1IDYsMCAxMCw3
IDEwLDE1IDAsOCA1LDE1IDEwLDE1IDYsMCAxMCw1IDEwLDEwIDAsMTAgOCwyMiAzOCw1NSA2LDcg
MTIsMTYgMTIsMjAgMCw0IDYsMTIgMTIsMTkgNyw4IDIwLDI0IDI4LDM2IDgsMTIgMjIsMzAgMzAs
NDEgMjgsMzYgNTUsNzAgNzAsODkgOCwxMCAyNiwzMyA0MCw1MSAyNSwzMiA1MCw2MSAxMjUsMTQ4
IDIyLDI1IDEwNSwxMTMgMTg1LDE5NCA3NTEsNzcxIDE3NTEsMTI5NiAyODA1LDE0NzEgMzgzLDY0
IDcyOCw4NSAxMDk1LDY2IHoiIC8+CiAgICA8L2c+CiAgPC9nPgogIDxnCiAgICAgaWQ9Imw2TTRl
a0s3NXBjN2NqNkVLMDI5cmhjIgogICAgIGZpbGw9IiNhMmEyYTMiCiAgICAgdHJhbnNmb3JtPSJt
YXRyaXgoMC4wMjI1MDE4LDAsMCwwLjAyMjUwMTgsLTgwLjQwNzA3OSwzLjIzMTY1NzYpIgogICAg
IHN0eWxlPSJmaWxsOiNlNmU2ZTY7ZmlsbC1vcGFjaXR5OjEiPgogICAgPGVsbGlwc2UKICAgICAg
IHN0eWxlPSJmaWxsOiNlNmU2ZTY7ZmlsbC1vcGFjaXR5OjE7c3Ryb2tlLXdpZHRoOjEuMjQ4NDgi
CiAgICAgICBpZD0icGF0aDkxMCIKICAgICAgIHJ5PSIxMTQuOTg1MzQiCiAgICAgICByeD0iMTE1
LjY5NjciCiAgICAgICBjeT0iMTIxLjA2ODA4IgogICAgICAgY3g9IjEyNS4yODY0OCIKICAgICAg
IHRyYW5zZm9ybT0ibWF0cml4KDQ0LjQ0MDg4OSwwLDAsNDQuNDQwODg5LDM1NzMuMzYyMSwtMTQz
LjYxNzc0KSIgLz4KICAgIDxnCiAgICAgICBpZD0iZzI2OSIKICAgICAgIHN0eWxlPSJmaWxsOiNl
NmU2ZTY7ZmlsbC1vcGFjaXR5OjEiIC8+CiAgPC9nPgogIDxnCiAgICAgaWQ9ImwxQ2Rhd0ZISDVB
VGVzajYzcG5zOWJlIgogICAgIGZpbGw9IiM4Nzg3ODgiCiAgICAgdHJhbnNmb3JtPSJtYXRyaXgo
MC4wMjI1MDE4LDAsMCwwLjAyMjUwMTgsLTgwLjQwNzA3OSwzLjIzMTY1NzYpIj4KICAgIDxnCiAg
ICAgICBpZD0iZzI4MyIgLz4KICA8L2c+CiAgPGcKICAgICBpZD0ibDY2VndsM3I5N3dZZkdIOVB4
WWtOQ2ciCiAgICAgZmlsbD0iIzAwZmEwNSIKICAgICB0cmFuc2Zvcm09Im1hdHJpeCgwLjAzMDgw
ODMsMCwwLDAuMDI4NTI0MjksLTE0OS44NjU1MSwtMjUuMzk1NTg4KSIKICAgICBzdHlsZT0ib3Bh
Y2l0eTowLjczO2ZpbGw6IzA0ZTI2ZTtmaWxsLW9wYWNpdHk6MSI+CiAgICA8ZwogICAgICAgaWQ9
ImcyOTEiCiAgICAgICBzdHlsZT0iZmlsbDojMDRlMjZlO2ZpbGwtb3BhY2l0eToxIj4KICAgICAg
PHBhdGgKICAgICAgICAgaWQ9InAxOUVEME4zMnIiCiAgICAgICAgIGQ9Im0gNzIxNSw3NzIwIGMg
LTU0LC0xOCAtMTIxLC03NiAtMTQ2LC0xMjcgbCAtMjQsLTQ4IC0zLC0yMjI1IGMgLTIsLTE1NDEg
MCwtMjIzNiA4LC0yMjYyIDE0LC00OSA4OSwtMTMwIDE0MiwtMTUzIDI0LC0xMSA0NiwtMjQgNDks
LTI5IDgsLTEwIDk1LC0xMCAxMTIsMSA3LDQgNzM3LDEwIDE2MjIsMTMgMTYwOCw1IDE2MTAsNSAx
NjU1LDI2IDU1LDI2IDEyMyw5OCAxNDAsMTQ4IDgsMjUgMTAsNjMgNiwxMDkgLTQsNDAgLTcsODEg
LTgsOTIgLTIsMjcgLTk4LDExNCAtMTQ1LDEzMSAtMzEsMTEgLTMwNSwxMyAtMTU2MCwxNCBIIDc1
NDAgdiAyMDMzIGMgMCwxNzIwIC0yLDIwNDEgLTE0LDIwODcgLTgsMzAgLTEyLDU4IC0xMCw2MiA1
LDggLTg5LDk4IC0xMjIsMTE2IC0zMiwxNyAtMTQxLDI0IC0xNzksMTIgeiIKICAgICAgICAgc3R5
bGU9ImZpbGw6IzA0ZTI2ZTtmaWxsLW9wYWNpdHk6MSIgLz4KICAgICAgPHBhdGgKICAgICAgICAg
aWQ9InBmZzF5SWxiOCIKICAgICAgICAgZD0ibSA3OTk1LDc3MTkgYyAtNTIsLTE2IC0xMjEsLTc0
IC0xNDQsLTEyMiAtMjgsLTU3IC0zNiwtMTMwIC0yMiwtMTg0IDE1LC01MyA4NywtMTM0IDE0Mywt
MTU4IDI0LC0xMSA0OSwtMjUgNTYsLTMzIDExLC0xMCAyNjcsLTEyIDEzMjUsLTEwIDEzMDgsMyAx
MzEyLDMgMTM1NywyNCA1NSwyNiAxMjMsOTggMTQwLDE0OCA4LDI1IDEwLDYzIDYsMTA5IC00LDQw
IC03LDgxIC04LDkyIC0yLDI3IC05OCwxMTQgLTE0NSwxMzEgLTMxLDExIC0yNzEsMTMgLTEzNTgs
MTMgLTc2NywtMSAtMTMzMywtNSAtMTM1MCwtMTAgeiIKICAgICAgICAgc3R5bGU9ImZpbGw6IzA0
ZTI2ZTtmaWxsLW9wYWNpdHk6MSIgLz4KICAgICAgPHBhdGgKICAgICAgICAgaWQ9InBFWTNWa0dj
UyIKICAgICAgICAgZD0ibSA4MDU1LDU2NDkgYyAtNTIsLTE2IC0xMjEsLTc0IC0xNDQsLTEyMiAt
MjgsLTU4IC0zNiwtMTMwIC0yMSwtMTg2IDE0LC01MiAxMDgsLTE1MyAxNTQsLTE2NSAxNSwtNCAz
NSwtMTQgNDMsLTIyIDEzLC0xMyA4NywtMTQgNTUyLC0xMiA1MjAsMyA1MzcsNCA1ODEsMjQgNTUs
MjYgMTIzLDk4IDE0MCwxNDggOCwyNSAxMCw2MyA2LDEwOSAtNCw0MCAtNyw4MSAtOCw5MiAtMiwy
NyAtOTgsMTE0IC0xNDUsMTMxIC0zMCwxMCAtMTQ5LDEzIC01ODMsMTMgLTMwMCwtMSAtNTU4LC01
IC01NzUsLTEwIHoiCiAgICAgICAgIHN0eWxlPSJmaWxsOiMwNGUyNmU7ZmlsbC1vcGFjaXR5OjEi
IC8+CiAgICAgIDxwYXRoCiAgICAgICAgIGlkPSJwdzQ2dUE0d3ciCiAgICAgICAgIGQ9Im0gOTcz
OCw1NjUwIGMgLTQyLC0xMyAtMTE1LC02NyAtMTM3LC0xMDMgLTMzLC01NCAtNDUsLTEyNyAtMzEs
LTE5NCAxMSwtNDkgMjAsLTY1IDY5LC0xMTMgMzEsLTMxIDY5LC02MCA4NSwtNjQgMTUsLTQgMzUs
LTE0IDQzLC0yMiAxMywtMTMgNzUsLTE1IDQ1MiwtMTIgNDk3LDMgNDg2LDIgNTY4LDkwIDUyLDU3
IDY3LDEwNSA1OSwxODkgLTMsMzUgLTcsNzUgLTgsODkgLTMsMzIgLTk0LDExNyAtMTQ1LDEzNiAt
MzAsMTAgLTEzMywxMyAtNDgzLDEzIC0yNDUsLTEgLTQ1NywtNCAtNDcyLC05IHoiCiAgICAgICAg
IHN0eWxlPSJmaWxsOiMwNGUyNmU7ZmlsbC1vcGFjaXR5OjEiIC8+CiAgICA8L2c+CiAgPC9nPgog
IDxnCiAgICAgaWQ9Imw1RWR2Mm9veXZ2ak91UTZGTlBRUzB5IgogICAgIGZpbGw9IiMxYTIwMWIi
CiAgICAgdHJhbnNmb3JtPSJtYXRyaXgoMC4wMjI1MDE4LDAsMCwwLjAyMjUwMTgsLTgwLjQwNzA3
OSwzLjIzMTY1NzYpIj4KICAgIDxnCiAgICAgICBpZD0iZzI5NSI+CiAgICAgIDxwYXRoCiAgICAg
ICAgIGlkPSJwNWgxUjRFangiCiAgICAgICAgIGQ9Im0gMTQzMzQsNDQ5MiBjIC0xNCwtMTIgLTI1
LC00MyAtMzcsLTEwMiAtMjEsLTEwNSAtMjEsLTEwMCAzLC0xMDAgMTEsMCAyMCw1IDIwLDEwIDAs
NiAxOCwxMCA0MSwxMCA0MywwIDc3LDE0IDk2LDM5IDEzLDE3IDE4LDExOCA3LDE0NSAtOSwyMyAt
MTAyLDIxIC0xMzAsLTIgeiIgLz4KICAgIDwvZz4KICA8L2c+CiAgPGcKICAgICBpZD0ibDdqeDhn
Tm9qbnphR3lrNXlocmYyV28iCiAgICAgZmlsbD0iIzBmMTgwNyIKICAgICB0cmFuc2Zvcm09Im1h
dHJpeCgwLjAyMjUwMTgsMCwwLDAuMDIyNTAxOCwtODAuNDA3MDc5LDMuMjMxNjU3NikiPgogICAg
PGcKICAgICAgIGlkPSJnMzAyIj4KICAgICAgPHBhdGgKICAgICAgICAgaWQ9InBKN0Q1SFVTMyIK
ICAgICAgICAgZD0ibSAxNDcyMCw1Mzk4IGMgLTEyLC02OCAtNywtMzA4IDYsLTMzMCAzLC00IDE2
LC04IDI4LC04IDMyLDAgMzYsMjYgMzYsMjM2IHYgMTc0IGggLTI5IGMgLTI4LDAgLTMwLC0yIC00
MSwtNzIgeiIgLz4KICAgICAgPHBhdGgKICAgICAgICAgaWQ9InAxMWE3ZDRWaGUiCiAgICAgICAg
IGQ9Im0gMTQ2NzAsNDk0MiBjIDAsLTI0IDcsLTQ2IDIwLC02MCAxMSwtMTIgMjAsLTMzIDIwLC00
NyAwLC0yMCA1LC0yNSAyNCwtMjUgMjYsMCAzMiwyMCAzOCwxMjAgbCAzLDQ1IC01MywzIC01Miwz
IHoiIC8+CiAgICAgIDxwYXRoCiAgICAgICAgIGlkPSJwMTNybzhEWGpOIgogICAgICAgICBkPSJt
IDE0MzIxLDQ1MjAgYyAtMTYsLTc1IC0xNSwtODMgMTIsLTc0IDEyLDMgMjksMTMgMzgsMjAgOCw4
IDI1LDE0IDM3LDE0IDE4LDAgMjIsNiAyMiwzMCAwLDI1IC00LDMwIC0zNSwzNiAtMTksMyAtMzUs
MTAgLTM1LDE1IDAsNSAtNiw5IC0xNCw5IC05LDAgLTE4LC0xOSAtMjUsLTUwIHoiIC8+CiAgICAg
IDxwYXRoCiAgICAgICAgIGlkPSJwdWdySlU3ZSIKICAgICAgICAgZD0ibSAxNDI2Nyw0MjUyIGMg
LTM2LC0xNTYgLTM2LC0xODcgMywtMjA3IDE3LC05IDMwLC0xOSAzMCwtMjQgMCwtOCAtODAsLTY2
IC0xMDEsLTczIC01LC0yIC0xOCwtMzEgLTI4LC02NCBsIC0xOCwtNjEgNDgsLTEzIGMgMjcsLTgg
NDksLTE5IDQ5LC0yNiAwLC03IDgsLTE1IDE4LC0xOCAxNywtNiAxOCwtMTYgMTQsLTExMiAtNCwt
ODQgLTIsLTEwOCA5LC0xMTUgOCwtNSA0NCwtOSA4MSwtOSBoIDY4IGwgMTgsMzcgYyAxOCwzNyAz
OSwxMDIgNjIsMTkxIDYsMjMgMTUsNDIgMjAsNDIgNiwwIDEwLDE4IDEwLDQxIDAsNjQgMjksMTc3
IDUwLDE5MiAyMSwxNCA1NCwxMzAgNDUsMTU1IC0zLDkgLTI5LDMyIC01OCw1MSAtNDYsMzAgLTYw
LDM0IC0xMTksMzUgLTQ3LDEgLTY4LDUgLTY4LDE0IDAsNiA1LDEyIDEwLDEyIDYsMCAxMCwxNCAx
MCwzMSAwLDI2IC0zLDMwIC0xNywyNCAtMzgsLTE2IC02MiwtMTYgLTg1LC0xIGwgLTIzLDE1IHog
bSAxMzIsLTM5MCBjIC05LC02NCAtMjcsLTEyMSAtMjgsLTg4IC0xLDMzIDIxLDE0NiAyOCwxNDYg
NCwwIDQsLTI2IDAsLTU4IHoiIC8+CiAgICA8L2c+CiAgPC9nPgogIDxnCiAgICAgaWQ9Imwyb1pu
VWVqVDhGTWlpWkF1OFM0ZlQ0IgogICAgIGZpbGw9IiMwOTEwMDMiCiAgICAgdHJhbnNmb3JtPSJt
YXRyaXgoMC4wMjI1MDE4LDAsMCwwLjAyMjUwMTgsLTgwLjQwNzA3OSwzLjIzMTY1NzYpIj4KICAg
IDxnCiAgICAgICBpZD0iZzMwNyI+CiAgICAgIDxwYXRoCiAgICAgICAgIGlkPSJwaE5temxJdm0i
CiAgICAgICAgIGQ9Im0gMTQ2MjYsNTY3OCBjIC0xMSwtMjMgLTIyLC03NCAtMjUsLTExMyAtNCwt
NTAgLTEzLC03OSAtMjksLTEwMiAtMTIsLTE3IC0yMiwtMzkgLTIyLC00OCAwLC0xOSAtMjIsLTQw
IC01NywtNTUgLTEzLC01IC0yMywtMTYgLTIzLC0yNSAwLC04IC00LC0xNSAtMTAsLTE1IC01LDAg
LTEwLC05IC0xMCwtMjAgMCwtMTEgLTcsLTIzIC0xNSwtMjYgLTgsLTQgLTE1LC0xNSAtMTUsLTI1
IDAsLTEwIC00LC0xOSAtOSwtMTkgLTEwLDAgLTE1LC0zNiAtMzEsLTI0NSAtNiwtNzcgLTIyLC0y
MTggLTM1LC0zMTQgLTIwLC0xNDAgLTIyLC0xNzcgLTEyLC0xODkgMTAsLTEzIDksLTE1IC04LC05
IC0yMCw3IC0yMCw3IC0xLC04IDIzLC0xNyAzMywtMTkgNDAsLTYgMyw1IC0xLDExIC05LDE1IC04
LDMgLTE1LDExIC0xNSwxNyAwLDggNCw4IDE1LC0xIDEyLC0xMCAxNCwtOCAxMCw5IC0yLDEyIDAs
MTkgNiwxNiA1LC00IDksLTE0IDEwLC0yMyAwLC0xNCAyLC0xMyA5LDMgNywxNyA5LDE3IDksMyAx
LC0xMCA3LC0xOCAxNSwtMTggMTcsMCAyNiwtMjIgMjYsLTU4IC0xLC0zMCAtMTUsLTUzIC00NCwt
NjkgLTEwLC02IC0yNCwtMjcgLTMxLC00NiAtNywtMjAgLTksLTM0IC00LC0zMSAxNSw5IDEwLC0x
MyAtNiwtMjYgLTgsLTcgLTE1LC0xNyAtMTUsLTIyIDAsLTE3IC00NCwtNjggLTU4LC02OCAtMTIs
MCAtMTIsNCAyLDE5IDEwLDExIDE2LDI2IDEzLDMzIC00LDkgLTYsOCAtNiwtNCAtMSwtMTAgLTcs
LTE1IC0xOSwtMTEgLTE1LDQgLTIxLC04IC0zNiwtNzQgLTEwLC00MyAtMjEsLTgzIC0yMywtOTAg
LTMsLTYgNiwtMTMgMTksLTE1IDIzLC00IDIzLC00IC01LC0xOCAtMTcsLTggLTMwLC0yNSAtMzUs
LTQ0IC04LC0yOCAtNiwtMzEgMTQsLTM0IDEzLC0yIDMxLDEgNDEsNyAxMiw2IDI1LDYgMzgsLTIg
MTgsLTkgMTgsLTkgNyw1IC0xMSwxNCAtOCwxOSAyMCwzOSAxOCwxMiAzNSwyNCAzNywyNSAxMSw5
IC0yNiw2NyAtNTAsODAgLTM2LDE4IC0zNiwyOSAtMSw1MSAxNSw5IDM3LDI2IDUwLDM3IDEzLDEy
IDQyLDI1IDY0LDMxIDQ4LDEyIDY2LDM3IDIxLDI5IC0xNSwtMiAtMzUsLTcgLTQzLC0xMCAtMTEs
LTQgLTEyLC0yIC00LDYgMTYsMTYgODQsMzEgODQsMTggMCwtNSA5LC03IDE5LC0zIDE5LDYgMTA3
LC00NSAxMjQsLTcyIDI5LC00NiA1MCwyNiAxMDcsMzYyIDQwLDIzOCA0NiwzMDUgMjksMzE2IC0x
MSw3IC0xMCw5IDQsOSA5LDAgMTcsNSAxNywxMCAwLDYgLTcsMTAgLTE1LDEwIC04LDAgLTE1LDUg
LTE1LDEwIDAsNiAtOSwyMCAtMjAsMzIgLTI5LDMxIC0yNSw0MSAxNCwzNCA0MSwtOCA0NiwyIDQ2
LDg0IDAsNDAgLTQsNTkgLTE0LDYzIC0zNiwxNCAtMjYsMzQ3IDEwLDM0NyAxMSwwIDE0LDI1IDE0
LDEyNCAwLDY4IC0zLDEzMSAtNiwxNDAgLTUsMTIgLTIxLDE2IC03MywxNiBsIC02NiwtMSB6IG0g
LTk5LC0xMjA1IGMgLTIsLTE2IC00LC01IC00LDIyIDAsMjggMiw0MCA0LDI4IDIsLTEzIDIsLTM1
IDAsLTUwIHogbSAtNCwtMTIwIDMsLTYzIGggLTMzIC0zMyBsIDI1LDUwIGMgMTQsMjcgMjYsNjIg
MjYsNzcgMiw0MCA3LDkgMTIsLTY0IHoiIC8+CiAgICAgIDxwYXRoCiAgICAgICAgIGlkPSJwdmFG
cllJaGciCiAgICAgICAgIGQ9Im0gMTQ1NzgsNDA2NyBjIC0zMCwtMjQgLTU4LC0xMTcgLTU4LC0x
OTQgMCwtMjQgLTQsLTQzIC0xMCwtNDMgLTUsMCAtMTQsLTE5IC0yMCwtNDIgLTQxLC0xNjEgLTcx
LC0yMjggLTEwMSwtMjI4IC0xNywwIC0xOSw1IC0xNSwzOCAyLDIwIDE2LDc4IDMwLDEyNyAxNCw1
MCAyOCwxMTAgMzEsMTM0IDMsMjMgNyw0NyAxMCw1MSAxMywyMSAtOSw0MCAtNDUsNDAgaCAtMzgg
bCAtMTAsLTY3IGMgLTYsLTM4IC0xNywtMTI0IC0yNSwtMTkzIC0xMCwtODkgLTE1LC0xMDkgLTE2
LC03MCAwLDMwIDQsNzMgOSw5NSAxMiw0OSA1LDcyIC0yMiw4MSAtMjAsNiAtMjAsNyA4LDE5IGwg
MjksMTMgLTQwLDEgYyAtMjIsMSAtNjAsOCAtODQsMTcgLTI0LDggLTQ1LDEzIC00NiwxMiAtOSwt
MTIgLTMyLC05OCAtMjcsLTEwMiA0LC0yIDM1LC03IDY4LC0xMSBsIDYxLC03IC0xLC05MSBjIC0x
LC04MyAxLC05NCAyMiwtMTE1IDE3LC0xNyAzMywtMjIgNzYsLTIyIDgwLDAgOTksMjAgMTM3LDE0
MyAxNyw1NiAzNSwxMTEgMzksMTIyIDE3LDQxIDMzLDEwMSAzNiwxMzQgMSwxOSA3LDM3IDEyLDQw
IDUsMyAxNCwyOSAyMSw1NiA2LDI4IDE0LDU4IDE3LDY4IDcsMjQgLTE1LDIyIC00OCwtNiB6IiAv
PgogICAgPC9nPgogIDwvZz4KICA8ZwogICAgIGlkPSJsMlNHbmduQllEOXBOZkdYQWNOMkJMMCIK
ICAgICBmaWxsPSIjMDYwOTAxIgogICAgIHRyYW5zZm9ybT0ibWF0cml4KDAuMDIyNTAxOCwwLDAs
MC4wMjI1MDE4LC04MC40MDcwNzksMy4yMzE2NTc2KSI+CiAgICA8ZwogICAgICAgaWQ9ImczMTYi
PgogICAgICA8cGF0aAogICAgICAgICBpZD0icHZRTUllUDJQIgogICAgICAgICBkPSJtIDE0NjMw
LDU3MzQgYyAtMjAsLTQgLTI4LC0xNCAtMzcsLTQ3IC00NiwtMTgwIC02MywtMjE0IC0xMzYsLTI3
OCBsIC01MiwtNDYgLTEwLC0xNzEgYyAtNSwtOTMgLTcsLTE2OCAtNCwtMTY2IDQsMiA5LC01IDEy
LC0xNiAzLC0xMSAxMiwtMjAgMjEsLTIwIDIzLDAgMjAsMzYgLTUsNTMgLTEzLDkgLTE2LDE3IC0x
MCwyMiA2LDMgMTEsMSAxMSwtNCAwLC02IDUsLTExIDEwLC0xMSA3LDAgNyw2IDAsMTkgLTUsMTEg
LTEwLDM1IC05LDUzIDEsMzAgMiwzMSA4LDggNiwtMjEgOSwtMTYgMTYsMzAgNSwzMCA4LDYxIDgs
NjcgMCw3IDMsMTAgOCw3IDUsLTMgMTIsOCAxNSwyNSA0LDE3IDEzLDMxIDIwLDMxIDgsMCAxMSw2
IDgsMTUgLTQsOSAzLDE4IDE3LDI1IDM3LDE1IDU5LDM2IDU5LDU1IDAsOSAxMCwzMSAyMiw0OCAx
NiwyMyAyNSw1MiAyOSwxMDIgMywzOSAxNCw5MCAyNSwxMTQgbCAxOSw0MiA1OCwtNSBjIDU3LC02
IDU4LC01IDUxLDE3IC0zLDEyIC03LDIzIC05LDI0IC00LDYgLTEyMiwxMSAtMTQ1LDcgeiIgLz4K
ICAgICAgPHBhdGgKICAgICAgICAgaWQ9InBCRXcxbFNCOCIKICAgICAgICAgZD0ibSAxNDQ1Myw1
MDAzIGMgLTYsLTEzIC05LC0zMiAtNiwtNDMgNCwtMTYgMTEsLTE5IDMyLC0xNCA1MiwxMyA5MCw0
MyA5MSw3MiAwLDkgLTE2LDEyIC01MywxMCAtNDUsLTIgLTU1LC02IC02NCwtMjUgeiBtIDY3LC03
IGMgMCwtNyAtMTEsLTE2IC0yNSwtMTggLTI5LC02IC0zMyw2IC03LDIxIDI0LDE0IDMyLDEzIDMy
LC0zIHoiIC8+CiAgICAgIDxwYXRoCiAgICAgICAgIGlkPSJwTlBMQkN0eEMiCiAgICAgICAgIGQ9
Im0gMTQ1MDEsNDY1NyBjIC01LC0xMiAtMTEsLTcxIC0xNSwtMTMwIC02LC0xMTAgLTE4LC0xNDgg
LTc1LC0yMzIgLTI5LC00MyAtMjcsLTQ3IDI1LC0zOSAzMyw1IDY2LDEgMTI0LC0xNiA4NSwtMjQg
MTEwLC0yMiAxMTAsMTAgMCwxNSAtNywyMCAtMjUsMjAgLTQwLDAgLTg1LDI3IC04Niw1MyAtNSw4
OSAtMywyNTcgNCwyNTcgMTAsMCA5LDMyIC00LDY5IC0xMywzNyAtNDUsNDIgLTU4LDggeiIgLz4K
ICAgICAgPHBhdGgKICAgICAgICAgaWQ9InB0clV3SjNmYSIKICAgICAgICAgZD0ibSAxNDIxNyw0
MDQzIGMgLTEwLC0zNyAtMTcsLTcyIC0xNSwtNzggNCwtMTQgMzksLTcgNzAsMTYgMTUsMTAgMzIs
MTkgMzgsMTkgMjYsMCA3LDQxIC0yOSw2NCAtMjEsMTQgLTQxLDMwIC00MywzNiAtMiw3IC0xMiwt
MTkgLTIxLC01NyB6IiAvPgogICAgICA8cGF0aAogICAgICAgICBpZD0icDEybzVVMFdUNSIKICAg
ICAgICAgZD0ibSAxNDU2MywzOTgyIGMgLTE3LC0xMSAtMzYsLTkzIC0yNCwtMTA1IDE2LC0xNiAz
OCwtMSA0NCwzMCA0LDE1IDksMzggMTMsNDkgNiwyMiAtMTQsMzggLTMzLDI2IHoiIC8+CiAgICAg
IDxwYXRoCiAgICAgICAgIGlkPSJwWmZGWGtxY0UiCiAgICAgICAgIGQ9Im0gMTQ1MTMsMzgwNyBj
IC01LC03IC0yMCwtNTAgLTMzLC05NyAtMzYsLTEzMSAtNjMsLTE3MCAtMTE3LC0xNzAgLTIwLDAg
LTYyLDMwIC02Myw0NSAwLDMgLTMsMTEgLTYsMTkgLTMsOCAtMSw0MCA1LDcyIDE4LDk0IDIwLDkx
IC01Niw5OSAtMzgsNCAtNzUsMTEgLTg0LDE2IC0xMyw2IC0xOCwzIC0yMywtMTQgLTMsLTEyIC02
LC0yNSAtNiwtMjkgMCwtMyAyOCwtOSA2MywtMTMgbCA2NCwtNyAtMSwtOTAgYyAtMSwtODYgMCwt
OTEgMjcsLTExNCA0MCwtMzQgMTI3LC0zNSAxNjEsLTEgMTgsMTggMTA2LDI0OSAxMDYsMjc4IDAs
MTMgLTI5LDE3IC0zNyw2IHoiIC8+CiAgICA8L2c+CiAgPC9nPgogIDxnCiAgICAgaWQ9Imw1YTdB
c1BvVm9sSXFyaWNjV1JRc3g3IgogICAgIGZpbGw9IiMwNTAzMDEiCiAgICAgdHJhbnNmb3JtPSJt
YXRyaXgoMC4wMjI1MDE4LDAsMCwwLjAyMjUwMTgsLTgwLjQwNzA3OSwzLjIzMTY1NzYpIj4KICAg
IDxnCiAgICAgICBpZD0iZzMyMyI+CiAgICAgIDxwYXRoCiAgICAgICAgIGlkPSJwYkFRRzk3Vm0i
CiAgICAgICAgIGQ9Im0gMTAwODUsMTA3MzAgYyA5MDcsLTE5NCAxNjg4LC01NzIgMjM5NSwtMTE2
MCAxNjEsLTEzNCA1MTYsLTQ4OSA2NTAsLTY1MCA0NTAsLTU0MiA3NzMsLTExMTkgOTkwLC0xNzcw
IDE4MywtNTQ4IDI3NywtMTExNiAyODEsLTE2ODkgMCwtOTAgNCwtMTYwIDcsLTE1NSA0LDUgMzks
MzggNzksNzMgNDAsMzUgNzEsNjYgNzEsNzAgLTEsMyAzLDE2IDEwLDI4IDExLDIwIDI5LDc5IDU2
LDE4MSA5LDM1IDE1LDQyIDM2LDQ0IDM1LDIgNDUsMSA4NywtNyBsIDM2LC02IC02LDExNSBjIC0x
NSwyNTkgLTY4LDU4NCAtMTQ3LDkwMSAtMTk5LDgwMyAtNTY0LDE1MTkgLTExMTAsMjE3NSAtMTM0
LDE2MSAtNDc5LDUwNiAtNjQwLDY0MCAtODAwLDY2NSAtMTcwNSwxMDcwIC0yNzI1LDEyMTkgLTE5
NCwyOSAtMjI1LDI1IC03MCwtOSB6IiAvPgogICAgICA8cGF0aAogICAgICAgICBpZD0icGhlNzAz
VzJ1IgogICAgICAgICBkPSJtIDE0NDgzLDQzNzIgYyAtNywtNCAtMjYsLTI4IC00MiwtNTIgbCAt
MzAsLTQ1IDM0LC0zIGMgMTksLTIgNTAsLTIgNjksMCBsIDM0LDMgLTIwLDUzIGMgLTIwLDUzIC0y
NCw1NyAtNDUsNDQgeiIgLz4KICAgICAgPHBhdGgKICAgICAgICAgaWQ9InBjTTUwRVNhVyIKICAg
ICAgICAgZD0ibSAxNDYxOSw0MjM1IGMgMTgsLTggMzgsLTEyIDQ0LC04IDEzLDggLTE5LDIxIC01
MywyMiAtMjMsMCAtMjIsLTEgOSwtMTQgeiIgLz4KICAgICAgPHBhdGgKICAgICAgICAgaWQ9InBZ
MDhJTXg0RyIKICAgICAgICAgZD0ibSAxNDUxNSwzNzk4IGMgLTQsLTEzIC0yOCwtOTkgLTMwLC0x
MDggMCwtMyAtOSwtMjkgLTIwLC01OSAtMzIsLTg3IC05MSwtMTIyIC0xNDMsLTg1IC0zNywyNiAt
NDUsNTkgLTMyLDEzNyA3LDM3IDEwLDcwIDksNzIgLTUsNCAtODYsMTQgLTEyMSwxNCAtMjAsMSAt
MjgsNiAtMjksMTkgMCw5IC0yNCwtNTAgLTUzLC0xMzMgLTEwNCwtMjk2IC0yNjQsLTY0NiAtNDE2
LC05MTAgLTU1LC05NiAtMjMyLC0zNzQgLTI2MCwtNDA4IC01LC02IC0zOCwtNTAgLTcyLC05NyAt
MzUsLTQ3IC02NiwtODkgLTcwLC05NSAtMjcsLTM3IC0xODgsLTIzMSAtMjQyLC0yOTIgLTYyLC03
MiAtMzkzLC00MDAgLTQ3MSwtNDY5IC0xMzIsLTExNiAtMzQ0LC0yODMgLTQzMCwtMzM4IC0xNiwt
MTEgLTM0LC0yMyAtNDAsLTI4IC01LC01IC03MywtNTEgLTE1MSwtMTAxIC03NywtNTEgLTE0OSwt
OTggLTE2MCwtMTA1IC0xMCwtNiAtMjUsLTE1IC0zMiwtMTggLTgsLTQgLTc1LC00MSAtMTUwLC04
MyBDIDExMzIxLDU1MyAxMTAzNSw0MjggMTA3MTAsMzIwIDEwMTYyLDEzNyA5NTk5LDQ0IDkwMTcs
MzggODc1NSwzNiA4OTA4LDIyIDkyODYsMTQgYyA1MjksLTEyIDkxNiwzMSAxNDE5LDE1NiA4MDMs
MTk5IDE1MTksNTY0IDIxNzUsMTExMCAxNjEsMTM0IDUwNiw0NzkgNjQwLDY0MCA0NDIsNTMxIDc2
OCwxMTA4IDk4NCwxNzM5IDI1LDczIDQ2LDEzNyA0NiwxNDIgMCwxNCAtMzAsMTEgLTM1LC0zIHoi
IC8+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4K
"
id="image1868"
x="45"
y="38.129822" /></g><text
xml:space="preserve"
transform="scale(0.26458333)"
id="text1615"
style="text-align:center;white-space:pre;shape-inside:url(#rect1617);fill:#000000" /><text
xml:space="preserve"
transform="scale(0.26458333)"
id="text1621"
style="fill:#000000;text-align:center;white-space:pre;shape-inside:url(#rect1623)" /><text
xml:space="preserve"
transform="scale(0.26458333)"
id="text1627"
style="fill:#000000;text-align:center;white-space:pre;shape-inside:url(#rect1629)" /><text
xml:space="preserve"
transform="scale(0.26458333)"
id="text1633"
style="text-align:center;white-space:pre;shape-inside:url(#rect1635);fill:#000000" /><text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,0.07578914,3.2788775)"
id="text1639"
style="font-size:14.6667px;text-align:center;white-space:pre;shape-inside:url(#rect1641);fill:#000000"><tspan
x="208.99142"
y="748.2969"
id="tspan2081">EvolutionOS is a general purpose operating system, </tspan><tspan
x="219.62263"
y="766.63028"
id="tspan2083">based onthe monolithic Linux kernel. Its package </tspan><tspan
x="225.71347"
y="784.96365"
id="tspan2085">systemallows you to quickly install, update and </tspan><tspan
x="226.94882"
y="803.29703"
id="tspan2087">removesoftware; software is provided in binary </tspan><tspan
x="214.66331"
y="821.6304"
id="tspan2089">packages orcan be built directly from sources with </tspan><tspan
x="220.74698"
y="839.96377"
id="tspan2091">the help of the XBPS source packages collection.</tspan></text></svg>
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

19
res/install.sh Executable file
View File

@ -0,0 +1,19 @@
#!/bin/sh
# uses PREFIX and DESTDIR from environment
: "${PREFIX:=/usr/local}"
set -e
DOC=${DESTDIR}${PREFIX}/share/doc/void
mkdir -p $DOC/
cp -r src/ $DOC/markdown
rm -fr $DOC/markdown/theme
cp -r book/html $DOC/html
cp -r mandoc/ $DOC/mandoc
install -Dm0644 res/void-docs.1 ${DESTDIR}${PREFIX}/share/man/man1/void-docs.1
install -Dm0755 res/void-docs ${DESTDIR}${PREFIX}/bin/void-docs
install -Dm0644 book/latex/handbook-a4.pdf ${DESTDIR}${PREFIX}/share/doc/void/handbook.pdf

123
res/mdbook-gemini Executable file
View File

@ -0,0 +1,123 @@
#!/usr/bin/perl
use strict;
use warnings;
use File::Which;
use File::Path qw(make_path);
use JSON;
# Accept input on stdin regardless of whether the 'md2gemini' executable
# is present, to avoid "Broken pipe" errors from mdBook.
my $data;
{
local $/;
undef $/;
$data = <>;
}
if (! defined which 'md2gemini') {
print "'md2gemini' not found in PATH; not building Gemini output\n";
# We can't return non-zero here, as that would cause the entire
# mdBook build process to fail.
exit 0;
}
my $json = JSON->new->decode($data);
my $sections = $json->{book}->{sections};
# Create toc.gmi from SUMMARY.md
my $leader;
open(my $summary, '<', '../../src/SUMMARY.md')
or die "Can't open SUMMARY.md for reading: $!\n";
open(my $toc, '>', 'toc.gmi')
or die "Can't open toc.gmi for writing: $!\n";
print $toc "# Table of Contents\n\n";
while (<$summary>) {
if (/^(\s*)- \[([^\]]+)\]\(([^\)]+)\)/) {
my $depth = $1;
my $heading = $2;
my $path = $3;
if (length($depth) == 0) {
$leader = '-';
} else {
$leader = '-' x (1 + (length($depth) / 3));
}
$path =~ s/\.md$/.gmi/;
print $toc "=> " . $path . " " . $leader . " " . $heading . "\n";
}
}
close($summary)
or die "Can't close SUMMARY.md after reading: $!\n";
close($toc)
or die "Can't close toc.gmi after writing: $!\n";
# Create individual pages.
foreach my $i (@$sections) {
process_json($i);
}
exit 0;
### Functions
sub process_json {
my $i = shift;
my $type = ref($i);
if ($type eq 'HASH') {
if (defined $i->{content}) {
process_content($i->{path},$i->{content});
}
if (defined $i->{Chapter}) {
process_json($i->{Chapter});
}
if (defined $i->{sub_items}) {
foreach my $j ($i->{sub_items}) {
process_json($j);
}
}
}
if ($type eq 'ARRAY') {
foreach my $j (@{$i}) {
process_json($j);
}
}
}
sub process_content {
my $path = shift;
my $directory = $path;
my $filename = $path;
my $content = shift;
my $fh;
$directory =~ s|/[^/]+\.md$||;
$filename =~ s|^.*/([^/]+)\.md$|$1.gmi|;
make_path($directory);
open($fh, "| md2gemini --links copy --md-links --ascii-table > " .
$directory . '/' . $filename)
or die "Can't open pipe to md2gemini: $!\n";
print $fh $content;
print $fh "\n\n" . "=> /toc.gmi Table of Contents" . "\n";
close $fh
or die "Can't close pipe to md2gemini: $!\n";
}

389
res/mdbook-latex Executable file
View File

@ -0,0 +1,389 @@
#!/usr/bin/perl
use strict;
use warnings;
use Cwd;
use JSON;
my $data;
{
local $/;
undef $/;
$data = <>;
}
my $json = JSON->new->decode($data);
my $sections = $json->{book}->{sections};
my $date = `date '+%d %B %Y'`;
chomp $date;
my $latex;
my %code_inline;
my $code_inline_index = 0;
my %codeblocks;
my $codeblock_index = 0;
# Opening.
$latex .= "\\documentclass[letterpaper]{article}\n";
$latex .= "\\usepackage[margin=4cm]{geometry}\n";
$latex .= "\\usepackage[T1]{fontenc}\n";
$latex .= "\\fontfamily{lmodern}\n";
$latex .= "\\selectfont\n";
$latex .= "\\usepackage{graphicx}\n";
$latex .= "\\usepackage{hyperref}\n";
$latex .= "\\usepackage{listings}\n";
$latex .= "\\lstdefinestyle{void}{\n";
$latex .= " basicstyle=\\ttfamily,\n";
$latex .= " breaklines=true,\n";
$latex .= " showstringspaces=false,\n";
$latex .= " aboveskip=\\bigskipamount,\n";
$latex .= " belowskip=\\bigskipamount,\n";
$latex .= "}\n";
$latex .= "\\def\\code#1{\\texttt{#1}}\n";
$latex .= "\\begin{document}\n";
$latex .= "\\newgeometry{margin=2cm}\n";
$latex .= "\\begin{titlepage}\n";
$latex .= " \\includegraphics[width=160mm,height=230mm]{res/handbook-cover.png}\n";
$latex .= "\\end{titlepage}\n";
$latex .=" \\restoregeometry\n";
$latex .= "\\title{EvolutionOS Handbook}\n";
$latex .= "\\date{$date}\n";
$latex .= "\\maketitle\n";
$latex .= "\\setcounter{tocdepth}{5}\n";
$latex .= "\\tableofcontents\n";
$latex .= "\\begin{sloppypar}\n"; # Ugly; need to find better solution
# Contents.
foreach my $i (@$sections) {
process_json($i);
}
# Postprocessing.
$latex =~ s/config-network-wpa\\_supplicant/config-network-wpa_supplicant/g;
$latex =~ s/config-network-wpa_supplicant-the-wpa\\_supplicant-service/config-network-wpa_supplicant-the-wpa_supplicant-service/g;
$latex =~ s/(handbook-codeblock-\d+)/$codeblocks{$1}/eg;
$latex =~ s/(handbook-codeinline-\d+)/$code_inline{$1}/eg;
# Closing.
$latex .= "\\end{sloppypar}\n";
$latex .= "\\end{document}\n";
open(my $fh, ">", "handbook.tex")
or die "Can't open handbook.tex for writing: $!";
print $fh $latex;
close($fh)
or die "Couldn't close handbook.tex after writing: $!";
exit 0;
sub process_json {
my $i = shift;
my $type = ref($i);
if ($type eq 'HASH') {
if (defined $i->{content}) {
process_content($i->{path},$i->{content});
}
if (defined $i->{Chapter}) {
process_json($i->{Chapter});
}
if (defined $i->{sub_items}) {
foreach my $j ($i->{sub_items}) {
process_json($j);
}
}
}
if ($type eq 'ARRAY') {
foreach my $j (@{$i}) {
process_json($j);
}
}
}
sub process_content {
my $path = shift;
my $content = shift;
my $base = convert_path_to_hypertarget_base($path);
# Create sections.
$content =~ s/^# ([^\n]+)/create_sectioning("section",$1,$base)/eg;
# Create subsections.
$content =~ s/\n## ([^\n]+)/create_sectioning("subsection",$1,$base)/eg;
# Create subsubsections.
$content =~ s/\n### ([^\n]+)/create_sectioning("subsubsection",$1,$base)/eg;
# Create paragraphs.
$content =~ s/\n#### ([^\n]+)/create_sectioning("paragraph",$1,$base)/eg;
# Create subparagraphs.
$content =~ s/\n##### ([^\n]+)/create_sectioning("subparagraph",$1,$base)/eg;
# Create codeblocks.
$content =~ s/```\n(.+?)\n```/create_codeblock($1)/esg;
# Create internal links.
$content =~ s/\[([^]]+?)\]\(((?:\..?.+?)|(?:#.+?))\)/create_internal_link($1,$2,$path)/esg;
# Create external links.
$content =~ s/<(http[^>]+)>/\\href{$1}{$1}/sg; # bare links
$content =~ s/\[([^]]+?)\]\((.+?)\)/\\href{$2}{$1}/sg;
# Create lists.
$content =~ s/\n\n(- .+?)\n(?:\n|\z)/create_list($1)/esg;
# Create numbered lists.
$content =~ s/\n\n(\d+\. .+?)\n(?:\n|\z)/create_numbered_list($1)/esg;
# Create blockquotes.
$content =~ s/((^>(?:\s*\n|[^\n]+))+)/create_blockquote($1)/emsg;
# Bold text.
$content =~ s/\*\*([^*]+)\*\*/{\\bfseries $1}/sg;
# Escape LaTeX special characters.
$content =~ s/#/'\#'/eg;
$content =~ s/\$/'\$'/eg;
$content =~ s/_/'\_'/eg;
$content =~ s/~/'\~'/eg;
$content =~ s/&/'\&'/eg;
$content =~ s/\^/'\^'/eg;
# Create tables.
$content =~ s/((?:(?:\| +[^|]+ +\| +(?:[^|]+ +\|)+\n)|(?:\|-[^\n]+\n))+)/create_table($1)/esg;
# Create inline code.
$content =~ s/(?: |\n)`([^`]+)`/create_code_inline($1)/esg;
$latex .= $content;
}
sub convert_heading_to_fragment {
my $heading = shift;
$heading =~ s/ /-/g;
$heading =~ s/\.//g;
$heading =~ s/\(|\)//g;
$heading =~ s/(.+)/lc($1)/e;
return $heading;
}
sub convert_path_to_hypertarget_base {
my $base = shift;
if ($base =~ m|index.md|) {
$base =~ m|(.+/index).md|;
$base = $1;
$base =~ s|/|-|g;
} else {
$base =~ m|(.+).md|;
$base = $1;
$base =~ s|/|-|g;
}
return $base;
}
sub create_blockquote {
my $blockquote = shift;
my $result;
$blockquote =~ s/>//g;
$blockquote =~ s/\n//g;
$result .= "\\begin{quote}\n";
$result .= $blockquote;
$result .= "\\end{quote}\n";
return $result;
}
sub create_codeblock {
my $codeblock = shift;
my $label;
my $result;
$codeblock_index++;
$label = 'handbook-codeblock-' . $codeblock_index;
$result .= "\\begin{lstlisting}[style=void]\n";
$result .= $codeblock;
$result .= "\n\\end{lstlisting}\n";
$codeblocks{$label} = $result;
# Mark places in document where codeblock will be re-inserted
# during postprocessing.
return $label;
}
sub create_code_inline {
my $code = shift;
my $label;
my $result;
$code_inline_index++;
$label = 'handbook-codeinline-' . $code_inline_index;
$result = " \\code{$code}";
$code_inline{$label} = $result;
# Mark places in document where code will be re-inserted
# during postprocessing.
return $label;
}
sub create_internal_link {
my $text = shift;
my $destination = shift;
my $current_section = shift;
my $current_directory;
my $base;
my $fragment;
my $hypertarget;
my $result;
if ($destination =~ /^#/) {
$base = $current_section . $destination;
$base =~ s|.md#.+$||;
} else {
$current_section =~ m|^(.+/)|;
$current_directory = $1;
$base = $destination;
$base =~ m|^(.+\.md)|;
$base = $1;
$base = $current_directory . $base;
$base = Cwd::abs_path("../../src/" . $base);
$base =~ s|^.+/src/||;
$base =~ s|.md||;
}
$base =~ s|/|-|g;
if ($destination =~ /#/) {
$destination =~ m|#(.+)$|;
$fragment = "-" . $1;
} else {
$fragment = "";
}
$text =~ s/\n/ /;
$hypertarget = $base . $fragment;
$result = "\\hyperlink{$hypertarget}{$text}";
return $result;
}
sub create_list {
my $list = shift;
my $result;
$result .= "\n\\begin{itemize}\n";
$list =~ s/^- /\\item /mg;
$result .= $list;
$result .= "\n\\end{itemize}\n";
return $result;
}
sub create_numbered_list {
my $list = shift;
my $result;
$result .= "\n\\begin{enumerate}\n";
$list =~ s/^\d+\. /\\item /mg;
$result .= $list;
$result .= "\n\\end{enumerate}\n";
return $result;
}
sub create_sectioning {
my $type = shift;
my $text = shift;
my $name = shift;
my $result;
if ($type ne "section") {
$name = $name . "-" . convert_heading_to_fragment($text);
$result .= "\n\\hypertarget{";
$result .= $name;
$result .= "}{}";
$result .= "\n\\$type\{$text\}\n";
} else {
$result .= "\n\\newpage\n";
$result .= "\n\\hypertarget{";
$result .= $name;
$result .= "}{}";
$result .= "\n\\$type\{$text\}\n";
}
return $result;
}
sub create_table {
my $table = shift;
my $result;
my @lines;
my $header;
my @body;
my $column_count;
@lines = split(/\n/, $table);
$header = $lines[0];
$header =~ s/[^|]//g;
$column_count = length($header) - 1;
$result .= "\n\\bigskip";
$result .= "\n\\begin{tabular}{ | ";
$result .= "l | " x ($column_count - 1);
$result .= "l | }\n";
$result .= "\\hline\n";
$header = $lines[0];
$header =~ s/^\|//;
$header =~ s/\|/&/g;
$header =~ s/&$//;
$result .= $header;
$result .= "\\\\ \\hline \\hline\n";
shift @lines;
foreach my $line (@lines) {
if ($line !~ /^\|-/) {
$line =~ s/^\|//;
$line =~ s/\|/&/g;
$line =~ s/&$//;
$result .= $line;
$result .= "\\\\ \\hline\n";
}
}
$result .= "\n\\end{tabular}\n";
$result .= "\n\\bigskip\n";
}

190
res/void-docs.1.in Normal file
View File

@ -0,0 +1,190 @@
.Dd October 09, 2020
.Dt VOID-DOCS 1
.Os
.Sh NAME
.Nm void-docs
.Nd Access Void Linux documentation
.Sh SYNOPSIS
.Nm
.Op OPTIONS
.Op search terms
.Sh DESCRIPTION
The
.Nm
utility will attempt to launch different programs until it can find an
adequate one to display the Void Linux documentation. If it is invoked
without a search term, it will show the documentation's home
page. Multiple search terms can be used to filter results. If the user
has the
.Xr fzf 1
or
.Xr sk 1
utilities installed in their system, it will be used to browse the
results. Otherwise,
.Nm
will immediately display the first search result. If the
.Fl s
flag is used,
.Nm
will display the search results instead of the documentation.
The programs
.Nm
will try to use are, in order of preference:
.Bl -dash
.It
For the HTML version:
.Bl -dash
.It
the program specified in the environment variable
.Ev BROWSER .
.It
.Xr xdg-open 1
if either the
.Ev DISPLAY
or
.Ev WAYLAND_DISPLAY
environment variable is set.
.It
.Xr run-mailcap 1 .
.It
the TUI browsers
.Xr lynx 1 ,
.Xr w3m 1 ,
and
.Xr links 1 .
.El
.It
For the Markdown version:
.Bl -dash
.It
the Markdown processors
.Sq mdcat
and
.Sq glow .
.El
.It
For the roff (mdoc) version:
.Bl -dash
.It
.Xr man 1 .
.El
.It
For the PDF version:
.Bl -dash
.It
.Xr xdg-open 1 ,
and
.Xr run-mailcap 1 .
.It
the PDF viewers
.Xr zathura 1
and
.Xr okular 1 .
.El
.El
.Pp
It should be noted that for the PDF version,
.Nm
doesn't support search results.
.Pp
For a better browsing experience, installing
.Xr fzf 1
is recommended.
.Sh OPTIONS
.Bl -tag -width -x
.It Fl h, Fl -help
Show help message.
.It Fl b
Only try to display the HTML version.
.It Fl m
Only try to display the Markdown version.
.It Fl r
Only try to display the roff (mdoc) version.
.It Fl p
Open the PDF version.
.It Fl s
Only display search results.
.El
.Sh FILES
The
.Sq void-docs
package contains a snapshot of the online documentation from
.Lk https://docs.voidlinux.org ,
which intends to document installation, configuration and system
management for Void Linux. It is packaged in four formats.
.Bl -tag -width x
.It Pa @PREFIX@/share/doc/void/html
Documentation in HTML format. Can be viewed with any browser, such as
Mozilla Firefox or Chromium. Recommended when a GUI session is
available, because it allows easy navigation between the documentation
pages and has the same format as the official website. Can be accessed
by pointing a browser to
.Pa @PREFIX@/share/doc/void/html/index.html .
.It Pa @PREFIX@/share/doc/void/markdown
Documentation in Markdown format. Can be viewed as text files, using
.Xr cat 1
or
.Xr less 1 ,
or as formatted Markdown files, using applications such as
.Sq mdcat
or
.Sq glow .
The table of contents can be accessed via the
.Pa @PREFIX@/share/doc/void/markdown/SUMMARY.md
file.
.It Pa @PREFIX@/share/doc/void/mandoc
Documentation in roff (mdoc) format. Can be viewed using
.Xr mandoc 1 .
Using
.Xr mandoc 1
with the
.Fl a
option, which enables a pager, is recommended.
.It Pa @PREFIX@/share/doc/void/handbook.pdf
Documentation in PDF format. Can be viewed with any PDF viewer, such as
.Xr zathura 1
or
.Xr okular 1 .
.Sh EXAMPLES
View the documentation page about the kernel:
.Pp
.Dl $ void-docs kernel
.Pp
View a documentation page inside another session:
.Pp
.Dl $ void-docs graphical-session kde
.Pp
View the homepage of the HTML documentation with
.Xr qutebrowser 1 :
.Pp
.Dl $ qutebrowser @PREFIX@/share/doc/void/html/index.html
.Pp
View the summary of the Markdown documentation with
.Xr less 1 :
.Pp
.Dl $ less @PREFIX@/share/doc/void/markdown/SUMMARY.md
.Pp
View the
.Dq Kernel
page of the Markdown documentation with
.Sq mdcat :
.Pp
.Dl $ mdcat @PREFIX@/share/doc/void/markdown/config/kernel.md
.Pp
View the
.Dq Cron
page of the roff (mdoc) documentation with
.Xr mandoc 1 :
.Pp
.Dl $ mandoc -a @PREFIX@/share/doc/void/mandoc/config/cron.7
.Pp
.Sh AVAILABILITY
This man page is part of the void-docs package and is available from
.Lk https://github.com/void-linux/void-docs .
.Sh BUGS
The Void Linux documentation tries to limit itself to content that is
specific to Void. Therefore, if you feel something is missing, it
might have been deliberate. However, if there is any information that
is mistaken, outdated or indeed missing, please report an issue at
.Lk https://github.com/void-linux/void-docs .

181
res/void-docs.in Normal file
View File

@ -0,0 +1,181 @@
#!/bin/sh
# This is the void linux documentation browser
[ "$DEBUG" ] && set -x
# turn on errors and noglob
set -fe
# document to open
VOIDDOC=
# terms to search for
TERMS=
# versions to try
_html=1
_md=1
_roff=1
_pdf=
usage() {
cat <<EOF
Welcome to the Void Linux documentation browser!
Usage: $0 [options] [search terms]
Options:
-h, --help: show this help text
-b: only try to display the HTML version
-m: only try to display the Markdown version
-r: only try to display the roff (mandoc) version
-p: open the PDF version
-s: only display search results
EOF
exit 0
}
while [ $# -gt 0 ]; do
case $1 in
-h|--help) usage ;;
-b) _html=1 ; _md= ; _roff= ;;
-m) _html= ; _md=1 ; _roff= ;;
-r) _html= ; _md= ; _roff=1 ;;
-p) _pdf=1 ;;
-s) _search=1 ;;
*)
if [ "$TERMS" ]; then
TERMS="$TERMS -and -iwholename *$1*"
else
TERMS="-iwholename *$1*"
fi
;;
esac
shift
done
: "${DOCS:=@PREFIX@/share/doc/void}"
if [ "$_pdf" ]; then
PDF="$DOCS/handbook.pdf"
if [ -n "$PDF_VIEWER" ] && command -v "$PDF_VIEWER" >dev/null; then
exec $PDF_VIEWER $PDF
elif command -v xdg-open >/dev/null; then
exec xdg-open $PDF
elif command -v run-mailcap >/dev/null; then
exec run-mailcap --action=view $PDF
else
for cmd in zathura okular evince
do
if command -v $cmd >/dev/null; then
exec $cmd $PDF
fi
done
fi
fi
# creates the appropriate path
find_page() {
case $1 in
html) VOIDDOC="$DOCS/html/$2.html" ;;
md) VOIDDOC="$DOCS/markdown/$2.md" ;;
man) VOIDDOC="$DOCS/mandoc/$2.7" ;;
esac
if [ -f "$VOIDDOC" ]; then
echo "$VOIDDOC"
else
echo "couldn't find file" >&2
return 1
fi
}
# knows how to open a certain page
open_page() {
if [ "$_html" ]; then
if [ -n "$BROWSER" ] && command -v $BROWSER >/dev/null; then
page=$(find_page html $1)
exec $BROWSER $page
fi
# check if wayland or X session
if [ -n "$WAYLAND_DISPLAY" -o -n "$DISPLAY" ] && command -v xdg-open >/dev/null; then
page=$(find_page html $1)
exec xdg-open $page
fi
if command -v run-mailcap >/dev/null; then
exec run-mailcap --action=view $PDF
fi
# if a browser or xdg-open weren't available, we can try other stuff
# cli browser
for viewer in lynx w3m links
do
if command -v $viewer >/dev/null; then
page=$(find_page html $1)
exec $viewer $page
fi
done
fi
if [ "$_md" ]; then
# markdown processor
_viewer=
if command -v mdcat >/dev/null; then
_viewer=mdcat
elif command -v lowdown >/dev/null; then
_viewer="lowdown -Tterm"
elif command -v glow >/dev/null; then
_viewer=glow
fi
if [ "$_viewer" ]; then
page=$(find_page md $1)
$_viewer $page | less -R
exit
fi
fi
if [ "$_roff" ]; then
# otherwise go for the man page
page=$(find_page man $1)
exec man -l $page
fi
echo "Couldn't find a program to display the documentation."
return 1
}
search_page() {
file="$(find $DOCS/markdown -type f $1 -printf "%P\n")"
[ -z "$file" ] && exit 1
if [ "$_search" ]; then
echo "$file"
return 0
fi
_pager="head -1"
if command -v fzf >/dev/null; then
_pager=fzf
elif command -v sk >/dev/null; then
_pager=sk
elif command -v pick >/dev/null; then
_pager=pick
fi
if [ $(IFS=' '; echo $file | wc -l) -gt 1 ]; then
file="$(echo "$file" | $_pager)"
fi
file="${file%.md}"
echo "$file"
}
page=about/index
[ "$TERMS" ] && page="$(search_page "$TERMS")"
if [ "$_search" ]; then
echo "$page"
exit 0
fi
open_page "$page"

86
src/SUMMARY.md Normal file
View File

@ -0,0 +1,86 @@
# Summary
- [About](./about/index.md)
- [History](./about/history.md)
- [About This Handbook](./about/about-this-handbook.md)
- [InfraDocs](./about/infradocs.md)
- [Installation](./installation/index.md)
- [Live Installers](./installation/live-images/index.md)
- [Prepare Installation Media](./installation/live-images/prep.md)
- [Partitioning Notes](./installation/live-images/partitions.md)
- [Installation Guide](./installation/live-images/guide.md)
- [Advanced Installation Guides](./installation/guides/index.md)
- [Installation via chroot
(x86/x86_64/aarch64)](./installation/guides/chroot.md)
- [Full Disk Encryption](./installation/guides/fde.md)
- [Root on ZFS](./installation/guides/zfs.md)
- [ARM Devices](./installation/guides/arm-devices/index.md)
- [Supported Platforms](./installation/guides/arm-devices/platforms.md)
- [musl](./installation/musl.md)
- [Configuration](./config/index.md)
- [Package Documentation](./config/package-documentation/index.md)
- [Manual Pages](./config/package-documentation/man.md)
- [Firmware](./config/firmware.md)
- [Locales and Translations](./config/locales.md)
- [Users and Groups](./config/users-and-groups.md)
- [Services and Daemons - runit](./config/services/index.md)
- [Per-User Services](./config/services/user-services.md)
- [Logging](./config/services/logging.md)
- [rc.conf, rc.local and rc.shutdown](./config/rc-files.md)
- [Cron](./config/cron.md)
- [Solid State Drives](./config/ssd.md)
- [Security](./config/security/index.md)
- [AppArmor](./config/security/apparmor.md)
- [Date and Time](./config/date-time.md)
- [Kernel](./config/kernel.md)
- [Power Management](./config/power-management.md)
- [Network](./config/network/index.md)
- [Firewalls](./config/network/firewalls.md)
- [wpa_supplicant](./config/network/wpa_supplicant.md)
- [IWD](./config/network/iwd.md)
- [NetworkManager](./config/network/networkmanager.md)
- [ConnMan](./config/network/connman.md)
- [Network Filesystems](./config/network-filesystems.md)
- [Session and Seat Management](./config/session-management.md)
- [Graphical Session](./config/graphical-session/index.md)
- [Graphics Drivers](./config/graphical-session/graphics-drivers/index.md)
- [AMD or ATI](./config/graphical-session/graphics-drivers/amd.md)
- [Intel](./config/graphical-session/graphics-drivers/intel.md)
- [NVIDIA](./config/graphical-session/graphics-drivers/nvidia.md)
- [NVIDIA
Optimus](./config/graphical-session/graphics-drivers/optimus.md)
- [Xorg](./config/graphical-session/xorg.md)
- [Wayland](./config/graphical-session/wayland.md)
- [Fonts](./config/graphical-session/fonts.md)
- [Icons](./config/graphical-session/icons.md)
- [GNOME](./config/graphical-session/gnome.md)
- [KDE](./config/graphical-session/kde.md)
- [Multimedia](./config/media/index.md)
- [ALSA](./config/media/alsa.md)
- [PipeWire](./config/media/pipewire.md)
- [PulseAudio](./config/media/pulseaudio.md)
- [sndio](./config/media/sndio.md)
- [Bluetooth](./config/bluetooth.md)
- [TeX Live](./config/texlive.md)
- [External Applications](./config/external-applications.md)
- [Printing](./config/print/index.md)
- [Containers and Virtual Machines](./config/containers-and-vms/index.md)
- [Chroots and Containers](./config/containers-and-vms/chroot.md)
- [libvirt](./config/containers-and-vms/libvirt.md)
- [LXC](./config/containers-and-vms/lxc.md)
- [OpenPGP](./config/openpgp.md)
- [PHP](./config/php.md)
- [XBPS Package Manager](./xbps/index.md)
- [Advanced Usage](./xbps/advanced-usage.md)
- [Repositories](./xbps/repositories/index.md)
- [Mirrors](./xbps/repositories/mirrors/index.md)
- [Changing Mirrors](./xbps/repositories/mirrors/changing.md)
- [Using Tor Mirrors](./xbps/repositories/mirrors/tor.md)
- [Restricted Packages](./xbps/repositories/restricted.md)
- [Custom Repositories](./xbps/repositories/custom.md)
- [Signing Repositories](./xbps/repositories/signing.md)
- [Troubleshooting XBPS](./xbps/troubleshooting/index.md)
- [Common Issues](./xbps/troubleshooting/common-issues.md)
- [Static XBPS](./xbps/troubleshooting/static.md)
- [Contributing](./contributing/index.md)
- [Contributing To evolution-docs](./contributing/evolution-docs/index.md)

49
src/about/about-this-handbook.md Normal file
View File

@ -0,0 +1,49 @@
# About This Handbook
This handbook is not an extensive guide on how to use and configure common Linux
software. The purpose of this document is to explain how to install, configure,
and maintain EvolutionOS systems, and to highlight the differences between common
Linux distributions and EvolutionOS.
To search for a particular term within the Handbook, select the 'magnifying
glass' icon, or press 's'.
Those looking for tips and tricks on how to configure a Linux system in general
should consult upstream software documentation. Additionally, the [Arch
Wiki](https://wiki.archlinux.org/) provides a fairly comprehensive outline of
common Linux software configuration, and a variety of internet search engines
are available for further assistance.
## Reading The Manuals
While this handbook does not provide a large amount of copy and paste
configuration instructions, it does provide links to the [man
pages](https://man.voidlinux.org/) for the referenced software wherever
possible.
To learn how to use the [man(1)](https://man.voidlinux.org/man.1) man page
viewer, run the command `man man`. It can be configured by editing
`/etc/man.conf`; read [man.conf(5)](https://man.voidlinux.org/man.conf.5) for
details.
EvolutionOS commonly uses the [mandoc](https://mandoc.bsd.lv/) toolset for man pages. mandoc was
formerly known as "mdocml", and is provided by the `mdocml` package.
## Example Commands
Examples in this guide may have snippets of commands to be run in your shell.
When you see these, any line beginning with `$` is run as your normal user.
Lines beginning with `#` are run as `root`. After either of these lines, there
may be example output from the command.
### Placeholders
Some examples include text with placeholders. Placeholders indicate where you
should substitute the appropriate information. For example:
```
# ln -s /etc/sv/<service_name> /var/service/
```
This means you need to substitute the text `<service_name>` with the actual
service name.

20
src/about/history.md Normal file
View File

@ -0,0 +1,20 @@
# History
Knowledge of the ancients, grepped from the Git logs themselves:
- 2008-09-26: first Git import of
[void-packages](https://github.com/void-linux/void-packages)
- 2009-08-17: first Git import of [xbps](https://github.com/void-linux/xbps)
- 2011-06-25: first systemd commit in void-packages
- 2013-03-01: first [musl](https://musl.libc.org/) toolchains added
- 2014-07-14: begin switching to [LibreSSL](https://www.libressl.org/)
- 2014-07-28: switch from systemd to [runit](http://smarden.org/runit/)
- 2015-07-09: full aarch64 support with `linux4.1`
- 2018-07-06: first use of [Terraform for GitHub
permissions](https://github.com/void-linux/void-infrastructure/tree/master/terraform),
for increased transparency
- 2021-03-05: begin
[switching](https://github.com/void-linux/void-packages/commit/d90dba0ae27c4bb22cbb1722f70e4ed6d599e473)
to [OpenSSL](https://www.openssl.org/)
- 2023-07-Idk: forked void-packages to evolution-packages
- 2023-07-Stillidk: created evolution-linux website

31
src/about/index.md Normal file
View File

@ -0,0 +1,31 @@
# About
Welcome to the EvolutionOS Handbook! Please be sure to read the "[About This
Handbook](./about-this-handbook.md)" section to learn how to use this
documentation effectively. A local copy of this handbook, in several formats,
can be [installed](../xbps/index.md) via the `evolution-docs` package and accessed
with the [evolution-docs(1)](https://hectabit.org/evolutionos/wiki) utility.
EvolutionOS is an [rolling
release](https://en.wikipedia.org/wiki/Rolling_release) Linux distribution, with a focus on stability over
[bleeding-edge](https://en.wikipedia.org/wiki/Bleeding_edge_technology). In
addition, there are several features that make EvolutionOS unique:
- The use of BusyBox over Coreutils, increasing speed and minimalism to an extream
- The [musl libc](https://musl.libc.org/), which focuses on standards compliance
and correctness, has first class support. This allows us to build certain
components for musl systems statically, which would not be practical on glibc
systems.
- [runit](../config/services/index.md) is used for
[init(8)](https://man.voidlinux.org/init.8) and service supervision. This
allows EvolutionOS to support musl as a second libc choice, which would not be
possible with [systemd](https://www.freedesktop.org/wiki/Software/systemd/).
A side effect of this decision is a core system with clean and efficient
operation, and a small code base.
- The use of the booster initramfs over dracut, speeding up system startup and
reducing image sizes
EvolutionOS is developed in the spare time of Tracker-Friendly, and is generally
considered stable enough for daily use. I do this for fun and hope that my
work will be useful to others.

6
src/about/infradocs.md Normal file
View File

@ -0,0 +1,6 @@
# InfraDocs
[InfraDocs](https://infradocs.voidlinux.org/) is the meta-manual for the Void
project systems management.
EvolutionOS doesn't make much use of this system.

39
src/config/bluetooth.md Normal file
View File

@ -0,0 +1,39 @@
# Bluetooth
Ensure the Bluetooth controller is not blocked. Use `rfkill` to check whether
there are any blocks and to remove soft blocks. If there is a hard block, there
is likely either a physical hardware switch or an option in the BIOS to enable
the Bluetooth controller.
```
$ rfkill
ID TYPE DEVICE SOFT HARD
0 wlan phy0 unblocked unblocked
1 bluetooth hci0 blocked unblocked
# rfkill unblock bluetooth
```
## Installation
Install the `bluez` package and enable the `bluetoothd` and `dbus` services.
Then, add your user to the `bluetooth` group and restart the `dbus` service, or
simply reboot the system. Note that restarting the `dbus` service may kill
processes making use of it.
To use an audio device such as a wireless speaker or headset, ALSA users need to
install the `bluez-alsa` package. [PulseAudio](./media/pulseaudio.md) users do
not need any additional software. [PipeWire](./media/pipewire.md) users need
`libspa-bluetooth`.
## Usage
Manage Bluetooth connections and controllers using `bluetoothctl`, which
provides a command line interface and also accepts commands on standard input.
Consult the [Arch Wiki](https://wiki.archlinux.org/index.php/Bluetooth#Pairing)
for an example of how to pair a device.
## Configuration
The main configuration file is `/etc/bluetooth/main.conf`.

114
src/config/containers-and-vms/chroot.md Normal file
View File

@ -0,0 +1,114 @@
# Creating and using chroots and containers
chroots and containers can be set up and used for many purposes, including:
- running glibc software on musl (and vice versa)
- running software in a more controlled or sandboxed environment
- creating a rootfs for bootstrapping a system
## Chroot Creation
### xvoidstrap
[`xvoidstrap(1)`](https://man.voidlinux.org/xvoidstrap.1) (from `xtools`) can be
used to create the chroot:
```
# mkdir <chroot_dir>
# XBPS_ARCH=<chroot_arch> xvoidstrap <chroot_dir> base-voidstrap <other_pkgs>
```
`<other_pkgs>` is only needed if you want to pre-install other packages in the
chroot.
### Manual Creation
Alternatively, this process can be done manually.
Create a directory that will contain the chroot, then install a base system in
it via the `base-voidstrap` package:
```
# mkdir -p "<chroot_dir>/var/db/xbps/keys"
# cp -a /var/db/xbps/keys/* "<chroot_dir>/var/db/xbps/keys"
# XBPS_ARCH=<chroot_arch> xbps-install -S -r <chroot_dir> -R <repository> base-voidstrap <other_pkgs>
```
The `<repository>` may [vary depending on
architecture](../../xbps/repositories/index.md#the-main-repository).
`<other_pkgs>` is only needed if you want to pre-install other packages in the
chroot.
## Chroot Usage
### xchroot
[`xchroot(1)`](https://man.voidlinux.org/xchroot.1) (from `xtools`) can be used
to automatically set up and enter the chroot.
### Manual Method
Alternatively, this process can be done manually.
If network access is required, copy `/etc/resolv.conf` into the chroot;
`/etc/hosts` may need to be copied as well.
Several directories then need to be mounted as follows:
```
# mount -t proc none <chroot_dir>/proc
# mount -t sysfs none <chroot_dir>/sys
# mount --rbind /dev <chroot_dir>/dev
# mount --rbind /run <chroot_dir>/run
```
Use [chroot(1)](https://man.voidlinux.org/chroot.1) to change to the new root,
then run programs and do tasks as usual. Once finished with the chroot, unmount
the chroot using [umount(8)](https://man.voidlinux.org/umount.8). If any
destructive actions are taken on the chroot directory without unmounting first,
you may need to reboot to repopulate the affected directories.
### Alternatives
#### Bubblewrap
[bwrap(1)](https://man.voidlinux.org/bwrap.1) (from the `bubblewrap` package)
has additional features like the ability for sandboxing and does not require
root access.
`bwrap` is very flexible and can be used in many ways, for example:
```
$ bwrap --bind <chroot_dir> / \
--dev /dev \
--proc /proc \
--bind /sys /sys \
--bind /run /run \
--ro-bind /etc/resolv.conf /etc/resolv.conf \
--ro-bind /etc/passwd /etc/passwd \
--ro-bind /etc/group /etc/group \
<command>
```
In this example, you will not be able to add or edit users or groups. When
running graphical applications with Xorg, you may need to also bind-mount
`~/.Xauthority` or other files or directories.
The [bwrap(1) manpage](https://man.voidlinux.org/bwrap.1) and the [Arch Wiki
article](https://wiki.archlinux.org/title/Bubblewrap#Usage_examples) contain
more examples of `bwrap` usage.
#### Flatpak
[Flatpak](../external-applications.md#flatpak) is a convenient option for
running many applications, including graphical or proprietary ones, on both
glibc and musl systems.
#### Application Containers
If a more integrated and polished solution is desired, EvolutionOS also [provides OCI
containers](https://github.com/void-linux/void-docker/pkgs/container/void-linux)
that work with tools like [docker](https://www.docker.com) and
[podman](https://man.voidlinux.org/podman.1). These containers do not require
the creation of a chroot directory before usage.

10
src/config/containers-and-vms/index.md Normal file
View File

@ -0,0 +1,10 @@
# Containers and Virtual Machines
This section describes how to set up some of the container and virtual machine
software available on EvolutionOS.
## Section Contents
- [Chroots and Containers](./chroot.md)
- [libvirt](./libvirt.md)
- [LXC](./lxc.md)

33
src/config/containers-and-vms/libvirt.md Normal file
View File

@ -0,0 +1,33 @@
# libvirt
[libvirt](https://libvirt.org/) is an API and daemon for managing platform
virtualization, supporting virtualization technologies such as LXC, KVM, QEMU,
Bhyve, Xen, VMWare, and Hyper-V.
To use libvirt, install the `libvirt` package, ensure the `dbus` package is
installed, and [enable](../services/index.md#enabling-services) the `dbus`,
`libvirtd`, `virtlockd` and `virtlogd` services. The `libvirtd` daemon can be
reconfigured at runtime via
[virt-admin(1)](https://man.voidlinux.org/virt-admin.1).
The `libvirt` package provides the [virsh(1)](https://man.voidlinux.org/virsh.1)
interface to libvirtd. `virsh` is an interactive shell and batch-scriptable tool
for performing management tasks, including creating, configuring and running
virtual machines, and managing networks and storage. Note that `virsh` usually
needs to be run as root, as described in the `virsh` man page:
> Most virsh commands require root privileges to run due to the communications
> channels used to talk to the hypervisor. Running as non root will return an
> error.
However, if you have the `polkit` and `dbus` packages installed and you enable
the `dbus` service, `libvirtd` will grant necessary privileges to any user added
to the `libvirt` group.
An alternative to `virsh` is provided by the `virt-manager` and
`virt-manager-tools` packages.
For general information on libvirt, refer to [the libvirt
wiki](https://wiki.libvirt.org/page/Main_Page) and [the wiki's
FAQ](https://wiki.libvirt.org/page/FAQ). For an introduction to libvirt usage,
refer to [the "VM lifecycle" page](https://wiki.libvirt.org/page/VM_lifecycle).

128
src/config/containers-and-vms/lxc.md Normal file
View File

@ -0,0 +1,128 @@
# LXC
The [Linux Containers project](https://linuxcontainers.org/) includes three
subprojects: [LXC](https://linuxcontainers.org/lxc/introduction/),
[LXD](https://linuxcontainers.org/lxd/introduction/) and
[LXCFS](https://linuxcontainers.org/lxcfs/introduction/). The project also
included the CGManager project, which has been deprecated in favor of the CGroup
namespace in recent kernels.
## Configuring LXC
Install the `lxc` package.
Creating and running privileged containers as `root` does not require any
configuration; simply use the various `lxc-*` commands, such as
[lxc-create(1)](https://man.voidlinux.org/lxc-create.1),
[lxc-start(1)](https://man.voidlinux.org/lxc-start.1),
[lxc-attach(1)](https://man.voidlinux.org/lxc-attach.1), etc.
### Creating unprivileged containers
User IDs (UIDs) and group IDs (GIDs) normally range from 0 to 65535.
Unprivileged containers enhance security by mapping UID and GID ranges inside
each container to ranges not in use by the host system. The unused host ranges
must be *subordinated* to the user who will be running the unprivileged
containers.
Subordinate UIDs and GIDs are assigned in the
[subuid(5)](https://man.voidlinux.org/subuid.5) and
[subgid(5)](https://man.voidlinux.org/subgid.5) files, respectively.
To create unprivileged containers, first edit `/etc/subuid` and `/etc/subgid` to
delegate ranges. For example:
```
root:1000000:65536
user:2000000:65536
```
In each colon-delimited entry:
- the first field is the user to which a subordinate range will be assigned;
- the second field is the smallest numeric ID defining a subordinate range; and
- the third field is the number of consecutive IDs in the range.
The [usermod(8)](https://man.voidlinux.org/usermod.8) program may also be used
to manipulate suborinated IDs.
Generally, the number of consecutive IDs should be an integer multiple of 65536;
the starting value is not important, except to ensure that the various ranges
defined in the file do not overlap. In this example, `root` controls UIDs (or,
from `subgid`, GIDs) ranging from 1000000 to 1065535, inclusive; `user` controls
IDs ranging from 2000000 to 2065535.
Before creating a container, the user owning the container will need an
[lxc.conf(5)](https://man.voidlinux.org/lxc.conf.5) file specifying the subuid
and subgid range to use. For root-owned containers, this file resides at
`/etc/lxc/default.conf`; for unprivileged users, the file resides at
`~/.config/lxc/default.conf`. Mappings are described in lines of the form
```
lxc.idmap = u 0 1000000 65536
lxc.idmap = g 0 1000000 65536
```
The isolated `u` character indicates a UID mapping, while the isolated `g`
indicates a GID mapping. The first numeric value should generally always be 0;
this indicates the start of the UID or GID range *as seen from within the
container*. The second numeric value is the start of the corresponding range *as
seen from outside the container*, and may be an arbitrary value within the range
delegated in `/etc/subuid` or `/etc/subgid`. The final value is the number of
consecutive IDs to map.
Note that, although the external range start is arbitrary, care must be taken to
ensure that the end of the range implied by the start and number does not extend
beyond the range of IDs delegated to the user.
If configuring a non-root user, edit `/etc/lxc/lxc-usernet` as root to specify a
network device quota. For example, to allow the user named `user` to create up
to 10 `veth` devices connected to the `lxcbr0` bridge:
```
user veth lxcbr0 10
```
The user can now create and use unprivileged containers with the `lxc-*`
utilities. To create a simple EvolutionOS container named `mycontainer`, use a command
similar to:
```
lxc-create -n mycontainer -t download -- \
--dist voidlinux --release current --arch amd64
```
You may substitute another architecture for `amd64`, and you may specify a
`musl` image by adding `--variant musl` to the end of the command. See the [LXC
Image Server](http://images.linuxcontainers.org) for a list of available
containers.
By default, configurations and mountpoints for system containers are stored in
`/var/lib/lxc`, while configurations for user containers and mountpoints are
stored in `~/.local/share/lxc`. Both of these values can be modified by setting
`lxc.lxcpath` in the
[lxc.system.conf(5)](https://man.voidlinux.org/lxc.system.conf.5) file. The
superuser may launch unprivileged containers in the system `lxc.lxcpath` defined
in `/etc/lxc/lxc.conf`; regular users may launch unprivileged containers in the
personal `lxc.lxcpath` defined in `~/.config/lxc/lxc.conf`.
All containers will share the same subordinate UID and GID maps by default. This
is permissible, but it means that an attacker who gains elevated access within
one container, and can somehow break out of that container, will have similar
access to other containers. To isolate containers from each other, alter the
`lxc.idmap` ranges in `default.conf` to point to a unique range *before* you
create each container. Trying to fix permissions on a container created with the
wrong map is possible, but inconvenient.
## LXD
LXD provides an alternative interface to LXC's `lxc-*` utilities. However, it
does not require the configuration described in [the previous section](#lxc).
Install the `lxd` package, and [enable](../services/index.md#enabling-services)
the `lxd` service.
LXD users must belong to the `lxd` group.
Use the `lxc` command to manage instances, as described
[here](https://linuxcontainers.org/lxd/getting-started-cli/#lxd-client).

25
src/config/cron.md Normal file
View File

@ -0,0 +1,25 @@
# Cron
[cron](https://en.wikipedia.org/wiki/Cron) is a daemon for running programs at
regular intervals. The programs and intervals are specified in a `crontab` file,
which can be edited with [crontab(1)](https://man.voidlinux.org/crontab.1).
Running `crontab -e` as the superuser will edit the system crontab; otherwise,
it will edit the crontab for the current user.
By default, a cron daemon is not installed. However, multiple cron
implementations are available, including
[cronie](https://github.com/cronie-crond/cronie/),
[dcron](http://www.jimpryor.net/linux/dcron.html),
[fcron](http://fcron.free.fr/) and more.
Once you have chosen and installed an implementation,
[enable](./services/index.md#enabling-services) the corresponding service. There
is also a generic `crond` service which is maintained by the alternatives
system, but there is no real benefit in using it and just makes your setup
harder to follow.
As an alternative to the standard cron implementations, you can use
[snooze(1)](https://man.voidlinux.org/snooze.1) together with the
`snooze-hourly`, `snooze-daily`, `snooze-weekly` and `snooze-monthly` services,
which are provided by the `snooze` package for this purpose. Each of these
services execute scripts in the respective `/etc/cron.*` directories.

83
src/config/date-time.md Normal file
View File

@ -0,0 +1,83 @@
# Date and Time
To view your system's current date and time information, as well as make direct
changes to it, use [date(1)](https://man.voidlinux.org/date.1).
## Timezone
The default system timezone can be set by linking the timezone file to
`/etc/localtime`:
```
# ln -sf /usr/share/zoneinfo/<timezone> /etc/localtime
```
> Note: If the variable `TIMEZONE` is set in `/etc/rc.conf`, it should be
> removed or commented out, as this will override what has been set with `ln` on
> reboot.
To change the timezone on a per user basis, the `TZ` variable can be exported
from your shell's profile:
```
export TZ=<timezone>
```
Note that setting the *timezone* does not set the *time* (or date); instead, it
simply specifies an offset from
[UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time), as described in
[timezone(3)](https://man.voidlinux.org/timezone.3).
## Hardware clock
By default, the hardware clock in EvolutionOS is stored as UTC. Windows does not use
UTC by default, and if you are dual-booting, this will conflict with EvolutionOS. You
can either change Windows to use UTC, or change EvolutionOS Linux to use `localtime` by
setting the `HARDWARECLOCK` variable in `/etc/rc.conf`:
```
export HARDWARECLOCK=localtime
```
For more details, see [hwclock(8)](https://man.voidlinux.org/hwclock.8).
## NTP
To maintain accuracy of your system's clock, you can use the [Network Time
Protocol](https://en.wikipedia.org/wiki/Network_Time_Protocol) (NTP).
EvolutionOS provides packages for three NTP daemons: NTP, OpenNTPD and Chrony.
Once you have installed an NTP daemon, you can [enable the
service](../config/services/index.md#managing-services) for it, either through
its own service or the `ntpd` service managed by
[xbps-alternatives(1)](https://man.voidlinux.org/xbps-alternatives.1).
### NTP
NTP is the official reference implementation of the Network Time Protocol.
The `ntp` package provides NTP and the `isc-ntpd` service.
For further information, visit [the NTP site](https://www.ntp.org/).
### OpenNTPD
OpenNTPD focuses on providing a secure, lean NTP implementation which "just
works" with reasonable accuracy for a majority of use-cases.
The `openntpd` package provides OpenNTPD and the `openntpd` service.
For further information, visit [the OpenNTPD site](https://www.openntpd.org/).
### Chrony
Chrony is designed to work well in a variety of conditions; it can synchronize
faster and with greater accuracy than NTP.
The `chrony` package provides Chrony and the `chronyd` service.
The Chrony site provides [a brief overview of its advantages over
NTP](https://chrony.tuxfamily.org/faq.html#_how_does_chrony_compare_to_ntpd), as
well as [a detailed feature comparison between Chrony, NTP and
OpenNTPD](https://chrony.tuxfamily.org/comparison.html).

102
src/config/external-applications.md Normal file
View File

@ -0,0 +1,102 @@
# External Applications
## Programming Languages
The EvolutionOS repositories have a number of Python and Lua packages. If possible,
install packages from the EvolutionOS repositories or consider packaging the library or
application you need. Packaging your application allows for easier system
maintenance and can benefit other EvolutionOS users, so consider making a pull
request for it. The contribution instructions can be found
[here](https://github.com/evolution-linux/evolution-packages/blob/master/CONTRIBUTING.md).
To keep packages smaller, EvolutionOS has separate `devel` packages for header files
and development tools. If you install a library or application via a language's
package manager (e.g. `pip`, `gem`), or compile one from source, you may need to
install the programming language's `-devel` package. This is specially relevant
for `musl` libc users, due to pre-built binaries usually targeting `glibc`
instead.
| Language | Package Manager | Evolution Package |
|----------|--------------------------------|-----------------|
| Python3 | pip, anaconda, virtualenv, etc | `python3-devel` |
| Python2 | pip, anaconda, virtualenv, etc | `python2-devel` |
| Ruby | gem | `ruby-devel` |
| lua | luarocks | `lua-devel` |
## Restricted Packages
Some packages have legal restrictions on their distribution (e.g. Discord), may
be too large, or have another condition that makes it difficult for EvolutionOS to
distribute. These packages have build templates, but the packages themselves are
not built or distributed. As such, they must be built locally. For more
information see the page on [restricted
packages](../xbps/repositories/restricted.md).
## Non-x86_64 Arch
The EvolutionOS build system runs on x86_64 servers, both for compiling and cross
compiling packages. However, some packages (e.g. `libreoffice`) do not support
cross-compilation. These packages have to be built locally on a computer running
the same architecture and libc as the system on which the package is to be used.
To learn how to build packages, refer to [the README for the evolution-packages
repository](https://github.com/evolution-linux/evolution-packages/blob/master/README.md).
## Flatpak
Flatpak is another method for installing external proprietary applications on
Linux. For information on using Flatpak with EvolutionOS, see the [official
Flatpak documentation](https://flatpak.org/setup/Void%20Linux/).
If sound is not working for programs installed using Flatpak,
[PulseAudio](./media/pulseaudio.md) auto-activation might not be working
correctly. Make sure PulseAudio is running before launching the program.
Note that Flatpak's sandboxing will not necessarily protect you from any
security and/or privacy-violating features of proprietary software.
### Troubleshooting
Some apps may not function properly (e.g. not being able to access the host
system's files). Some of these issues can be fixed by installing one or more of
the `xdg-desktop-portal`, `xdg-desktop-portal-gtk`, `xdg-user-dirs`,
`xdg-user-dirs-gtk` or `xdg-utils` packages.
Some Flatpaks require [D-Bus](./session-management.md#d-bus) and/or
[Pulseaudio](./media/pulseaudio.md).
## AppImages
An [AppImage](https://appimage.org/) is a file that bundles an application with
everything needed to run it. An AppImage can be used by making it executable and
running it; installation is not required. AppImages can be run in a sandbox,
such as [firejail](https://firejail.wordpress.com/).
Some of the applications for which an AppImage is available can be found on
[AppImageHub](https://appimage.github.io/).
AppImages do not yet work on musl installations.
## Octave Packages
Some Octave packages require external dependencies to compile and run. For
example, to build the control package, you must install the `openblas-devel`,
`libgomp-devel`, `libgfortran-devel`, `gcc-fortran`, and `gcc` packages.
## MATLAB
To use MATLAB's help browser, live scripts, add-on installer, and simulink,
install the `libselinux` package.
## Steam
Steam can be installed either via a native package, which requires [enabling the
"nonfree" repository](../xbps/repositories/index.md#nonfree), or via
[Flatpak](#flatpak). The list of dependencies for different platforms and
troubleshooting information for the native package can be found in its
[Evolution-specific documentation](./package-documentation/index.html), while this
section deals with potential issues faced by Flatpak users.
If you are using a different drive to store your game library, the
`--filesystem` option from
[flatpak-override(1)](https://man.voidlinux.org/flatpak-override.1) can prove
useful.

39
src/config/firmware.md Normal file
View File

@ -0,0 +1,39 @@
# Firmware
EvolutionOS provides a number of firmware packages in the repositories. Some firmware
is only available if you have enabled the
[nonfree](../xbps/repositories/index.md#nonfree) repository.
## Microcode
Microcode is loaded onto the CPU or GPU at boot by the BIOS, but can be replaced
later by the OS itself. An update to microcode can allow a CPU's or GPU's
behavior to be modified to work around certain yet to be discovered bugs,
without the need to replace the hardware.
### Intel
Install the Intel microcode package, `intel-ucode`. This package is in the
nonfree repo, which has to be [enabled](../xbps/repositories/index.md#nonfree).
After installing this package, it is necessary to regenerate your
[initramfs](./kernel.md#kernel-hooks). For subsequent updates, the microcode
will be added to the initramfs automatically.
### AMD
Install the AMD package, `linux-firmware-amd`, which contains microcode for both
AMD CPUs and GPUs. AMD CPUs and GPUs will automatically load the microcode, no
further configuration required.
### Verification
The `/proc/cpuinfo` file has some information under `microcode` that can be used
to verify the microcode update.
## Removing firmware
By default, `linuxX.Y` packages and the `base-system` package install a number
of firmware packages. It is not necessary to remove unused firmware packages,
but if you wish to do so, you can configure XBPS to
[ignore](../xbps/advanced-usage.md#ignoring-packages) those packages, then
remove them.

17
src/config/graphical-session/fonts.md Normal file
View File

@ -0,0 +1,17 @@
# Fonts
To customize font display in your graphical session, you can use configurations
provided in `/usr/share/fontconfig/conf.avail/`. To do so, create a symlink to
the relevant `.conf` file in `/etc/fonts/conf.d/`, then use
[xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) to
reconfigure the `fontconfig` package.
For example, to disable use of bitmap fonts:
```
# ln -s /usr/share/fontconfig/conf.avail/70-no-bitmaps.conf /etc/fonts/conf.d/
# xbps-reconfigure -f fontconfig
```
Use [fc-conflist(1)](https://man.voidlinux.org/fc-conflist.1) to list which
configurations are in effect.

29
src/config/graphical-session/gnome.md Normal file
View File

@ -0,0 +1,29 @@
# GNOME
## Pre-installation
GNOME supports both X and Wayland sessions. Follow the "[Wayland](./wayland.md)"
or "[Xorg](./xorg.md)" sections to setup your preferred environment.
Install the `dbus` package, ensure the `dbus` service is enabled, and reboot for
the changes to take effect.
## Installation
Install the `gnome` package for a GNOME environment which includes the base
GNOME desktop and a subset of GNOME applications. Additional applications are
available via the `gnome-apps` package.
A minimal GNOME environment can be created by installing the `gnome-core`
package. Note, however, that not all GNOME features may be present or
functional.
If you require [ZeroConf](http://www.zeroconf.org/) support, install the `avahi`
package and enable the `avahi-daemon` service.
## Starting GNOME
The `gdm` package provides the `gdm` service for the GNOME Display Manager;
[test the service](../services/index.md#testing-services) before enabling it.
GDM defaults to providing a Wayland session via the `mutter` window manager, but
an X session can be chosen instead.

30
src/config/graphical-session/graphics-drivers/amd.md Normal file
View File

@ -0,0 +1,30 @@
# AMD or ATI
AMD GPU support requires the `linux-firmware-amd` package. If you have installed
the `linux` or `linux-lts` packages, it will be installed as a dependency. If
you installed a version-specific kernel package (e.g., `linux5.4`), it may be
necessary to manually install `linux-firmware-amd`.
## OpenGL
Install the Mesa DRI package, `mesa-dri`. This is already included in the `xorg`
meta-package, but it is needed when installing Xorg via `xorg-minimal` or for
running a Wayland compositor.
## Vulkan
Install `vulkan-loader`, the Khronos Vulkan Loader. Then install one or both of
the Mesa AMD Vulkan driver, `mesa-vulkan-radeon`; or the GPUOpen AMD Vulkan
driver, `amdvlk`.
## Xorg
Installing the `xorg` meta-package will pull in both `xf86-video-amdgpu` and,
for older hardware, `xf86-video-ati`. If you install `xorg-minimal`, choose one
of these Xorg driver packages to match your hardware. The `amdgpu` driver should
support cards built on AMD's "Graphics Core Next 1.2" architecture, introduced
circa 2012.
## Video acceleration
Install the `mesa-vaapi` and `mesa-vdpau` packages.

11
src/config/graphical-session/graphics-drivers/index.md Normal file
View File

@ -0,0 +1,11 @@
# Graphics Drivers
This section covers basic graphics setup depending on the hardware configuration
of your system.
## Section Contents
- [AMD or ATI](./amd.md)
- [Intel](./intel.md)
- [NVIDIA](./nvidia.md)
- [NVIDIA Optimus](./optimus.md)

48
src/config/graphical-session/graphics-drivers/intel.md Normal file
View File

@ -0,0 +1,48 @@
# Intel
Intel GPU support requires the `linux-firmware-intel` package. If you have
installed the `linux` or `linux-lts` packages, it will be installed as a
dependency. If you installed a version-specific kernel package (e.g.,
`linux5.4`), it may be necessary to manually install `linux-firmware-intel`.
## OpenGL
OpenGL requires the Mesa DRI package, `mesa-dri`. This is provided by the `xorg`
meta-package, but will need to be installed manually when using the
`xorg-minimal` package or running a Wayland compositor.
## Vulkan
Install the Khronos Vulkan Loader and the Mesa Intel Vulkan driver packages,
respectively `vulkan-loader` and `mesa-vulkan-intel`.
## Video acceleration
Install the `intel-video-accel` meta-package:
This will install all the Intel VA-API drivers. `intel-media-driver` will be
used by default, but this choice can be overridden at runtime via the
environment variable `LIBVA_DRIVER_NAME`:
| Driver Package | Supported GPU Gen | Explicit selection |
|----------------------|-------------------|--------------------------|
| `libva-intel-driver` | up to Coffee Lake | `LIBVA_DRIVER_NAME=i965` |
| `intel-media-driver` | from Broadwell | `LIBVA_DRIVER_NAME=iHD` |
## Troubleshooting
The kernels packaged by EvolutionOS are configured with
`CONFIG_INTEL_IOMMU_DEFAULT_ON=y`, which can lead to issues with their graphics
drivers, as reported by the [kernel
documentation](https://www.kernel.org/doc/html/latest/x86/iommu.html#graphics-problems).
To fix this, it is necessary to disable IOMMU for the integrated GPU. This can
be done by adding `intel_iommu=igfx_off` to your [kernel
cmdline](../../kernel.md#cmdline). This problem is expected to happen on the
Broadwell generation of internal GPUs. If you have another internal GPU and your
issues are fixed by this kernel option, you should file a bug reporting the
problem to kernel developers.
For newer Intel chipsets, the [DDX](../xorg.md#ddx) drivers may interfere with
correct operation. This is characterized by graphical acceleration not working
and general graphical instability. If this is the case, try removing all
`xf86-video-*` packages.

96
src/config/graphical-session/graphics-drivers/nvidia.md Normal file
View File

@ -0,0 +1,96 @@
# NVIDIA
## nouveau (Open Source Driver)
This is a reverse engineered driver largely developed by the community, with
some documentation provided by Nvidia. It tends to perform well on older
hardware, and is required to use a large portion of the available Wayland
compositors.
At the time of writing, graphics cards starting with second generation Maxwell
(GTX 9xx) are unable to perform at their full potential with `nouveau`. This is
because the `linux-firmware` collection is missing signed firmware blobs needed
to reclock these cards past their boot frequencies.
To use `nouveau` with Wayland, you only need the `mesa-dri` package, which
provides the accelerated OpenGL driver. On X11, you also need an appropriate
Xorg driver. You can either install `xf86-video-nouveau` or use the universal
`modesetting` driver bundled with Xorg (this is the only option on Tegra based
ARM boards). The former can make use of GPU-specific 2D acceleration paths,
which is primarily useful on older cards with specialized fixed function
hardware (the `modesetting` driver will accelerate 2D using OpenGL via GLAMOR).
When in doubt, it's a good idea to try `xf86-video-nouveau` first.
Note: `xf86-video-nouveau` is usually installed by default if you use the `xorg`
metapackage. If you use `xorg-minimal`, you will need to install it manually,
either directly or through `xorg-video-drivers`.
## nvidia (Proprietary Driver)
The proprietary drivers are available in the [nonfree
repository](../../../xbps/repositories/index.md#nonfree).
Check if your graphics card belongs to the [legacy
branch](https://www.nvidia.com/en-us/drivers/unix/legacy-gpu/). If it does not,
install the `nvidia` package. Otherwise you should install the appropriate
legacy driver, `nvidia470` or `nvidia390`. The older legacy driver, `nvidia340`,
is no longer available, and users are encouraged to [switch to
nouveau](#reverting-from-nvidia-to-nouveau).
| Brand | Type | Model | Driver Package |
|--------|-------------|----------------|----------------|
| NVIDIA | Proprietary | 800+ | `nvidia` |
| NVIDIA | Proprietary | 600/700 | `nvidia470` |
| NVIDIA | Proprietary | 400/500 Series | `nvidia390` |
The proprietary driver integrates in the kernel through
[DKMS](../../kernel.md#dynamic-kernel-module-support-dkms).
This driver offers better performance and power handling, and is recommended
where performance is needed.
## 32-bit program support (glibc only)
In order to run 32-bit programs with driver support, you need to install
additional packages.
If using the `nouveau` driver, install the `mesa-dri-32bit` package.
If using the `nvidia` driver, install the `nvidia<x>-libs-32bit` package. `<x>`
represents the legacy driver version (`470` or `390`) or can be left empty for
the main driver.
## Reverting from nvidia to nouveau
### Uninstalling nvidia
In order to revert to the `nouveau` driver, install the [`nouveau`
driver](#nouveau-open-source-driver) (if it was not installed already), then
remove the `nvidia`, `nvidia470`, or `nvidia390` package, as appropriate.
If you were using the obsolete `nvidia340` driver, you might need to install the
`libglvnd` package after removing the `nvidia340` package.
### Keeping both drivers
It is possible to use the `nouveau` driver while still having the `nvidia`
driver installed. To do so, remove the blacklisting of `nouveau` in
`/etc/modprobe.d/nouveau_blacklist.conf`, `/usr/lib/modprobe.d/nvidia.conf`, or
`/usr/lib/modprobe.d/nvidia-dkms.conf` by commenting it out:
```
#blacklist nouveau
```
For Xorg, specify that it should load the `nouveau` driver rather than the
`nvidia` driver by creating the file `/etc/X11/xorg.conf.d/20-nouveau.conf` with
the following content:
```
Section "Device"
Identifier "Nvidia card"
Driver "nouveau"
EndSection
```
You may need to reboot your system for these changes to take effect.

95
src/config/graphical-session/graphics-drivers/optimus.md Normal file
View File

@ -0,0 +1,95 @@
# NVIDIA Optimus
NVIDIA Optimus refers to a dual graphics configuration found on laptops
consisting of an Intel integrated GPU and a discrete NVIDIA GPU.
There are different methods to take advantage of the NVIDIA GPU, which depend on
the driver version supported by your hardware.
In order to determine the correct driver to install, it is not enough to look at
the "Supported Products" list on NVIDIA's website, because they are not
guaranteed to work in an Optimus configuration. So the only way is to try
installing the latest `nvidia`, rebooting, and looking at the kernel log. If
your device is not supported, you will see a message like this:
```
NVRM: The NVIDIA GPU xxxx:xx:xx.x (PCI ID: xxxx:xxxx)
NVRM: installed in this system is not supported by the xxx.xx
NVRM: NVIDIA Linux driver release. Please see 'Appendix
NVRM: A - Supported NVIDIA GPU Products' in this release's
NVRM: README, available on the Linux driver download page
NVRM: at www.nvidia.com.
```
which means you have to uninstall `nvidia` and install the legacy `nvidia390`.
A summary of the methods supported by EvolutionOS, which are mutually exclusive:
[PRIME Render Offload](#prime-render-offload)
- available on `nvidia` and `nvidia470`
- allows to switch to the NVIDIA GPU on a per-application basis
- more flexible but power saving capabilities depend on the hardware (pre-Turing
devices are not shut down completely)
Offloading Graphics Display with RandR 1.4
- available on `nvidia`, `nvidia470`, and `nvidia390`
- allows to choose which GPU to use at the start of the X session
- less flexible, but allows the user to completely shut down the NVIDIA GPU when
not in use, thus saving power
[Bumblebee](#bumblebee)
- available on `nvidia`, `nvidia470`, and `nvidia390`
- allows to switch to the NVIDIA GPU on a per-application basis
- unofficial method, offers poor performance
[Nouveau PRIME](#nouveau-prime)
- uses the open source driver `nouveau`
- allows to switch to the NVIDIA GPU on a per-application basis
- `nouveau` is a reverse-engineered driver and offers poor performance
You can check the currently used GPU by searching for `renderer string` in the
output of the `glxinfo` command. It is necessary to install the `glxinfo`
package for this. For the first two alternatives below, it is also possible to
verify that a process is using the NVIDIA GPU by checking the output of
`nvidia-smi`.
## PRIME Render Offload
In this method, GPU switching is done by setting environment variables when
executing the application to be rendered on the NVIDIA GPU. The wrapper script
`prime-run` is available from the `nvidia` package, and can be used as shown
below:
```
$ prime-run <application>
```
For more information, see NVIDIA's
[README](https://download.nvidia.com/XFree86/Linux-x86_64/440.44/README/primerenderoffload.html)
## Bumblebee
Enable the `bumblebeed` service and add the user to the `bumblebee` group. This
requires a re-login to take effect.
Run the application to be rendered on the NVIDIA GPU with `optirun`:
```
$ optirun <application>
```
## Nouveau PRIME
This method uses the open source `nouveau` driver. If the NVIDIA drivers are
installed, it is necessary to [configure the system to use
`nouveau`](./nvidia.md#reverting-from-nvidia-to-nouveau).
Set `DRI_PRIME=1` to run an application on the NVIDIA GPU:
```
$ DRI_PRIME=1 <application>
```

18
src/config/graphical-session/icons.md Normal file
View File

@ -0,0 +1,18 @@
# Icons
## GTK
By default, GTK-based applications try to use the Adwaita icon theme for
application icons. Consequently, installation of the `gtk+3` package will also
install the `adwaita-icon-theme` package. If you wish to use a different theme,
install the relevant package, then specify the theme in
`/etc/gtk-3.0/settings.ini` or `~/.config/gtk-3.0/settings.ini`.
`adwaita-icon-theme` can be removed after
[ignoring](../../xbps/advanced-usage.md#ignoring-packages) the package.
For information about how to specify a different GTK icon theme in
`settings.ini`, refer to [the GtkSettings
documentation](https://developer.gnome.org/gtk3/stable/GtkSettings.html#GtkSettings.properties),
in particular the
"[gtk-icon-theme-name](https://developer.gnome.org/gtk3/stable/GtkSettings.html#GtkSettings--gtk-icon-theme-name)"
property.

11
src/config/graphical-session/index.md Normal file
View File

@ -0,0 +1,11 @@
# Graphical Session
In order to configure a graphical session, you need:
- [Graphics drivers](./graphics-drivers/index.md)
- A basis for your graphical session: [Xorg](./xorg.md) or
[Wayland](./wayland.md)
You may also need:
- [Session management tools](../session-management.md)

34
src/config/graphical-session/kde.md Normal file
View File

@ -0,0 +1,34 @@
# KDE
## Installation
Install the `kde5` package, and optionally, the `kde5-baseapps` package.
To use the "Networks" widget, enable the `dbus` and `NetworkManager` services.
Installing the `kde5` package also installs the `sddm` package, which provides
the `sddm` service for the Simple Desktop Display Manager. This service depends
on the `dbus` service being enabled; [test the
service](../services/index.md#testing-services) before enabling it. If you are
not intending to run SDDM via a remote X server, you will need to install either
the `xorg-minimal` package or the `xorg` package. By default, SDDM will start an
X-based Plasma session, but you can request a Wayland-based Plasma session
instead.
If you wish to start an X-based session from the console, use
[startx](./xorg.md#startx) to run `startplasma-x11`. For a Wayland-based
session, run `startplasma-wayland` directly.
## Dolphin
Dolphin is the default file manager of the KDE desktop environment. It can be
installed on its own by installing the `dolphin` package, or it can be installed
as part of the `kde5-baseapps` meta-package.
### Thumbnail Previews
To enable thumbnail file previews, install the `kdegraphics-thumbnailers`
package. If you want video thumbnails, the `ffmpegthumbs` package is also
necessary. Enable previews in "Control" -> "Configure Dolphin" -> "General" ->
"Previews" by checking the corresponding boxes. File previews will be shown for
the selected file types after clicking "Preview" in Dolphin's toolbar.

94
src/config/graphical-session/wayland.md Normal file
View File

@ -0,0 +1,94 @@
# Wayland
This section details the manual installation and configuration of Wayland
compositors and related services and utilities.
## Installation
Unlike [Xorg](./xorg.md), Wayland implementations combine the display server,
the window manager and the compositor in a single application.
### Desktop Environments
GNOME, KDE Plasma and Enlightenment have Wayland sessions. GNOME uses its
Wayland session by default. When using these desktop environments, applications
built with GTK+ will automatically choose the Wayland backend, while Qt5 and EFL
applications might require [setting some environment
variables](#native-applications) if used outside KDE or Enlightenment,
respectively.
### Standalone compositors
EvolutionOS currently packages the following Wayland compositors:
- Weston: reference compositor for Wayland
- Sway: an i3-compatible Wayland compositor
- Wayfire: 3D Wayland compositor
- Hikari: a stacking compositor with some tiling features
- Cage: a Wayland kiosk
- River: a dynamic tiling Wayland compositor
- labwc: a window-stacking compositor, inspired by Openbox
Note that evolution-desktop exists, which uses Wayfire and bundles gtkgreet and polkit for
ease of access.
### Video drivers
Both GNOME and KDE Plasma have EGLStreams backends for Wayland, which means they
can use the proprietary NVIDIA drivers. Most other Wayland compositors require
drivers that implement the GBM interface. The main driver for this purpose is
provided by the `mesa-dri` package. The "[Graphics
Drivers](./graphics-drivers/index.md)" section has more details regarding
setting up graphics in different systems.
### Seat management
Wayland compositors require some way of controlling the video display and
accessing input devices. In EvolutionOS systems, this requires a seat manager service,
which can be either elogind or seatd. Enabling them is explained in the
["Session and Seat Management"](../session-management.md) session.
### Native applications
[Qt5](https://wayland.freedesktop.org/qt5.html)-based applications require
installing the `qt5-wayland` package and setting the environment variable
`QT_QPA_PLATFORM=wayland-egl` to enable their Wayland backend. Some KDE specific
applications also require installing the `kwayland` package.
[EFL](https://wayland.freedesktop.org/efl.html)-based applications require
setting the environment variable `ELM_DISPLAY=wl`, and can have issues without
it, due to not supporting XWayland properly. [SDL](https://libsdl.org)-based
applications require setting the environment variable `SDL_VIDEODRIVER=wayland`.
[GTK+](https://wiki.gnome.org/Initiatives/Wayland/GTK%2B)-based applications
should use the Wayland backend automatically. Information about other toolkits
can be found in the [Wayland
documentation](https://wayland.freedesktop.org/toolkits.html).
Media applications, such as [mpv(1)](https://man.voidlinux.org/mpv.1),
[vlc(1)](https://man.voidlinux.org/vlc.1) and `imv` work natively on Wayland.
#### Web browsers
Mozilla Firefox ships with a Wayland backend which is disabled by default. To
enable the Wayland backend, either set the environment variable
`MOZ_ENABLE_WAYLAND=1` before running `firefox` or use the provided
`firefox-wayland` script.
Browsers based on GTK+ or Qt5, such as Midori and
[qutebrowser(1)](https://man.voidlinux.org/qutebrowser.1), should work on
Wayland natively.
#### Running X applications inside Wayland
If an application doesn't support Wayland, it can still be used in a Wayland
context. XWayland is an X server that bridges this gap for most Wayland
compositors, and is installed as a dependency for most of them. Its package is
`xorg-server-xwayland`. For Weston, the correct package is `weston-xwayland`.
## Configuration
The Wayland library requires the
[`XDG_RUNTIME_DIR`](../session-management.html#xdg_runtime_dir) environment
variable to determine the directory for the Wayland socket.
It is also possible that some applications use the `XDG_SESSION_TYPE`
environment variable in some way, which requires that you set it to `wayland`.

128
src/config/graphical-session/xorg.md Normal file
View File

@ -0,0 +1,128 @@
# Xorg
This section details the manual installation and configuration of the Xorg
display server and common related services and utilities. If you would just like
to install a full desktop environment, it is recommended to try the [xfce
image](../../installation/live-images/index.md#xfce-image).
## Installation
EvolutionOS provides a comprehensive `xorg` package which installs the server and all
of the free video drivers, input drivers, fonts, and base applications. This
package is a safe option, and should be adequate for most systems which don't
require proprietary video drivers.
If you would like to select only the packages you need, the `xorg-minimal`
package contains the base xorg server *only*. If you install only
`xorg-minimal`, you will likely need to install a font package (like
`xorg-fonts`), a terminal emulator (like `xterm`), and a window manager to have
a usable graphics system.
## Video Drivers
EvolutionOS provides both open-source and proprietary (non-free) video drivers.
### Open Source Drivers
Xorg can use two categories of open source drivers: DDX or modesetting.
#### DDX
The DDX drivers are installed with the `xorg` package by default, or may be
installed individually if the `xorg-minimal` package was installed. They are
provided by the `xf86-video-*` packages.
For advanced configuration, see the man page corresponding to the vendor name,
like [intel(4)](https://man.voidlinux.org/intel.4).
#### Modesetting
Modesetting requires the `mesa-dri` package, and no additional vendor-specific
driver package.
Xorg defaults to DDX drivers if they are present, so in this case modesetting
must be explicitly selected: see [Forcing the modesetting
driver](#forcing-the-modesetting-driver).
For advanced configuration, see
[modesetting(4)](https://man.voidlinux.org/modesetting.4).
### Proprietary Drivers
EvolutionOS also provides [proprietary NVIDIA drivers](./graphics-drivers/nvidia.md),
which are available in the [nonfree
repository](../../xbps/repositories/index.md#nonfree).
## Input Drivers
A number of input drivers are available for Xorg. If `xorg-minimal` was
installed and a device is not responding, or behaving unexpectedly, a different
driver may correct the issue. These drivers can grab everything from power
buttons to mice and keyboards. They are provided by the `xf86-input-*` packages.
## Xorg Configuration
Although Xorg normally auto-detects drivers and configuration is not needed, a
config for a specific keyboard driver may look something like a file
`/etc/X11/xorg.conf.d/30-keyboard.conf` with the contents:
```
Section "InputClass"
Identifier "keyboard-all"
Driver "evdev"
MatchIsKeyboard "on"
EndSection
```
### Forcing the modesetting driver
Create the file `/etc/X11/xorg.conf.d/10-modesetting.conf`:
```
Section "Device"
Identifier "GPU0"
Driver "modesetting"
EndSection
```
and restart Xorg. Verify that the configuration has been picked up with:
```
$ grep -m1 '(II) modeset([0-9]+):' /var/log/Xorg.0.log
```
If there is a match, modesetting is being used.
## Starting X Sessions
### startx
The `xinit` package provides the [startx(1)](https://man.voidlinux.org/startx.1)
script as a frontend to [xinit(1)](https://man.voidlinux.org/xinit.1), which can
be used to start X sessions from the console. For example, to start
[i3(1)](https://man.voidlinux.org/i3.1), edit `~/.xinitrc` to contain `exec
/bin/i3` on the last line.
To start arbitrary programs together with an X session, add them in `~/.xinitrc`
before the last line. For example, to start
[pipewire(1)](https://man.voidlinux.org/pipewire.1) before starting i3, add
`pipewire &` before the last line.
A `~/.xinitrc` file which starts `pipewire` and `i3` is shown below:
```
pipewire &
exec /bin/i3
```
Then call `startx` to start a session.
If a D-Bus session bus is required, you can [manually start
one](../session-management.md#d-bus).
### Display Managers
Display managers (DMs) provide a graphical login UI. A number of DMs are
available in the EvolutionOS repositories, including `greetd / gtkgreet` (the recommended DM),`gdm` (the GNOME DM), `sddm` (the
KDE DM) and `lightdm`. When setting up a display manager, be sure to [test the
service](../services/index.md#testing-services) before enabling it.

4
src/config/index.md Normal file
View File

@ -0,0 +1,4 @@
# Configuration
This section and its subsections provide information about configuring your EvolutionOS
system.

250
src/config/kernel.md Normal file
View File

@ -0,0 +1,250 @@
# Kernel
## Kernel series
EvolutionOS provides many kernel series in the default repository. These are
named `linux<x>.<y>`: for example, `linux4.19`. You can query for all available
kernel series by running:
```
$ xbps-query --regex -Rs '^linux[0-9.]+-[0-9._]+'
```
The `linux` meta package, installed by default, depends on one of the kernel
packages, usually the package containing the latest mainline kernel that works
with all DKMS modules. Newer kernels might be available in the repository, but
are not necessarily considered stable enough to be the default; use these at
your own risk. If you wish to use a more recent kernel and have DKMS modules
that you need to build, install the relevant `linux<x>.<y>-headers` package,
then use [xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) to
reconfigure the `linux<x>.<y>` package you installed. This will build the DKMS
modules.
## Removing old kernels
When updating the kernel, old versions are left behind in case it is necessary
to roll back to an older version. Over time, old kernel versions can accumulate,
consuming disk space and increasing the time taken by DKMS module updates.
Furthermore, if `/boot` is a separate partition and fills up with old kernels,
updating can fail or result in incomplete initramfs filesystems to be generated
and result in kernel panics if they are being booted. Thus, it may be advisable
to clean old kernels from time to time.
Removing old kernels is done using the
[vkpurge(8)](https://man.voidlinux.org/vkpurge.8) utility. `vkpurge` comes
pre-installed on every Void Linux system. This utility runs the necessary
[hooks](#kernel-hooks) when removing old kernels. Note that `vkpurge` does not
remove kernel *packages*, only particular *kernels*.
## Removing the default kernel series
If you've installed a kernel package for a series other than the default, and
want to remove the default kernel packages, you should install the `linux-base`
package or [mark it as a manual package](https://man.voidlinux.org/xbps-pkgdb.1)
in case it is already installed. After this procedure, you can remove the
default kernel packages with
[xbps-remove(1)](https://man.voidlinux.org/xbps-remove.1). It might be necessary
to add `linux` and `linux-headers` to an `ignorepkg` entry in
[xbps.d(5)](https://man.voidlinux.org/xbps.d.5), since base packages can depend
on them.
## Switching to another kernel series
If you'd like to use the `linux-lts` or `linux-mainline` kernel series instead
of the default `linux`, first install the desired series metapackage (and the
`linux-lts-headers` or `linux-mainline-headers` metapackage if needed). Then you
can add `linux` and `linux-headers` to an `ignorepkg` entry in
[xbps.d(5)](https://man.voidlinux.org/xbps.d.5) and uninstall those packages.
## Changing the default initramfs generator
By default, EvolutionOS uses [dracut](https://man.voidlinux.org/dracut.8) to
prepare initramfs images for installed kernels. Alternatives such as
[mkinitcpio](https://man.voidlinux.org/mkinitcpio.8) are available. Each
initramfs generator registers an [XBPS
alternative](https://man.voidlinux.org/xbps-alternatives.1) in the `initramfs`
group to link its [kernel hooks](#kernel-hooks) to be used when creating or
removing initramfs images for a given kernel.
To replace dracut with, *e.g.*, mkinitcpio, install the `mkinitcpio` package;
confirm that `mkinitcpio` appears in the list of available alternatives by
running
```
$ xbps-alternatives -l -g initramfs
```
Issue the command
```
# xbps-alternatives -s mkinitcpio
```
to replace the dracut kernel hooks with those provided by mkinitcpio. With
subsequent kernel updates (or updates to DKMS packages that trigger initramfs
regeneration), mkinitcpio will be used instead of dracut to prepare initramfs
images. To force images to regenerate, reconfigure your kernel packages by
invoking
```
# xbps-reconfigure -f linux<x>.<y>
```
for each `linux<x>.<y>` package that is currently installed.
## cmdline
The kernel, the initial RAM disk (initrd) and some system programs can be
configured at boot by kernel command line arguments. The parameters understood
by the kernel are explained in the [kernel-parameters
documentation](https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html)
and by [bootparam(7)](https://man.voidlinux.org/bootparam.7). Parameters
understood by dracut can be found in
[dracut.cmdline(7)](https://man.voidlinux.org/dracut.cmdline.7).
Once the system is booted, the current kernel command line parameters can be
found in the `/proc/cmdline` file. Some system programs can change their
behavior based on the parameters passed in the command line, which is what
happens when [booting a different
runsvdir](./services/index.md#booting-a-different-runsvdir), for example.
There are different ways of setting these parameters, some of which are
explained below.
### GRUB
Kernel command line arguments can be added through the GRUB bootloader by
editing `/etc/default/grub`, changing the `GRUB_CMDLINE_LINUX_DEFAULT` variable
and then running `update-grub`.
### dracut
Dracut offers a [`kernel_cmdline` configuration
option](https://man.voidlinux.org/dracut.conf.5) and [`--kernel-cmdline`
command-line option](https://man.voidlinux.org/dracut.8) that will encode
command-line arguments directly in the initramfs image. When dracut is used to
create a UEFI executable, arguments set with these options will be passed to the
kernel. However, when an ordinary initramfs is produced, these options will
*not* be passed to the kernel at boot. Instead, they will be written to a
configuration file in `/etc/cmdline.d` within the image. While dracut parses
this configuration to control its own boot-time behavior, the kernel itself will
not be aware of anything set via this mechanism.
After modifying a dracut configuration, [regenerate](#kernel-hooks) the
initramfs to ensure that it includes the changes.
## Kernel hardening
EvolutionOS Linux ships with some kernel security options enabled by default. This was
originally provided by kernel command line arguments `slub_debug=P
page_poison=1`, but since kernel series 5.3, these have been replaced with
`init_on_alloc` and `init_on_free` (see [this
commit](https://github.com/torvalds/linux/commit/6471384af)).
Evolution's kernels come with the `init_on_alloc` option enabled by default where
available (i.e. `linux5.4` and greater). In most cases you should usually not
disable it, as it has a fairly minimal impact on performance (within 1%). The
`init_on_free` option is more expensive (around 5% on average) and needs to be
enabled manually by passing `init_on_free=1` on the kernel command line. If you
need to disable `init_on_alloc`, you can do that similarly by passing
`init_on_alloc=0`.
There is a chance that your existing system still has the old options enabled.
They still work in newer kernels, but have a performance impact more in line
with `init_on_free=1`. On older hardware this can be quite noticeable. If you
are running a kernel series older than 5.4, you can keep them (or add them) for
extra security at the cost of speed; otherwise you should remove them.
## Kernel modules
Kernel modules are typically drivers for devices or filesystems.
### Loading kernel modules during boot
Normally the kernel automatically loads required modules, but sometimes it may
be necessary to explicitly specify modules to be loaded during boot.
To load kernel modules during boot, a `.conf` file like
`/etc/modules-load.d/virtio.conf` needs to be created with the contents:
```
# load virtio-net
virtio-net
```
### Blacklisting kernel modules
Blacklisting kernel modules is a method for preventing modules from being loaded
by the kernel. There are two different methods for blacklisting kernel modules,
one for modules loaded by the initramfs and one for modules loaded after the
initramfs process is done. Modules loaded by the initramfs have to be
blacklisted in the initramfs configuration.
To blacklist modules loaded after the initramfs process, create a `.conf` file,
like `/etc/modprobe.d/radeon.conf`, with the contents:
```
blacklist radeon
```
#### Blacklisting modules in the initramfs
After making the necessary changes to the configuration files, the initramfs
needs to be [regenerated](#kernel-hooks) for the changes to take effect on the
next boot.
##### dracut
Dracut can be configured to not include kernel modules through a configuration
file. To blacklist modules from being included in a dracut initramfs, create a
`.conf` file, like `/etc/dracut.conf.d/radeon.conf`, with the contents:
```
omit_drivers+=" radeon "
```
##### mkinitcpio
To blacklist modules from being included in a mkinitcpio initramfs a `.conf`
file needs to be created like `/etc/modprobe.d/radeon.conf` with the contents:
```
blacklist radeon
```
## Kernel hooks
EvolutionOS provides directories for kernel hooks in
`/etc/kernel.d/{pre-install,post-install,pre-remove,post-remove}`.
These hooks are used to update the boot menus for bootloaders like `grub`,
`gummiboot` and `lilo`.
### Install hooks
The `{pre,post}-install` hooks are executed by
[xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) when
configuring a Linux kernel, such as building its initramfs. This happens when a
kernel series is installed for the first time or updated, but can also be run
manually:
```
# xbps-reconfigure --force linux<x>.<y>
```
If run manually, they serve to apply initramfs configuration changes to the next
boot.
### Remove hooks
The `{pre,post}-remove` hooks are executed by
[vkpurge(8)](https://man.voidlinux.org/vkpurge.8) when removing old kernels.
## Dynamic Kernel Module Support (DKMS)
There are kernel modules that are not part of the Linux source tree that are
built at install time using DKMS and [kernel hooks](#kernel-hooks). The
available modules can be listed by searching for `dkms` in the package
repositories.
DKMS build logs are available in `/var/lib/dkms/`.

30
src/config/locales.md Normal file
View File

@ -0,0 +1,30 @@
# Locales and Translations
For a list of currently enabled locales, run
```
$ locale -a
```
## Enabling locales
To enable a certain locale, un-comment or add the relevant lines in
`/etc/default/libc-locales` and [force-reconfigure](../xbps/index.md) the
`glibc-locales` package.
## Setting the system locale
Set `LANG=xxxx` in `/etc/locale.conf`.
## Application locale
Some programs have their translations in a separate package that must be
installed in order to use them. You can
[search](../xbps/index.md#finding-files-and-packages) for the desired language
(e.g. "german" or "portuguese") in the package repositories and install the
packages relevant to the applications you use. An especially relevant case is
when installing individual packages from the LibreOffice suite, such as
`libreoffice-writer`, which require installing at least one of the
`libreoffice-i18n-*` packages to work properly. This isn't necessary when
installing the `libreoffice` meta-package, since doing so will install the most
common translation packages.

55
src/config/media/alsa.md Normal file
View File

@ -0,0 +1,55 @@
# ALSA
To use ALSA, install the `alsa-utils` package and make sure your user is a
member of the `audio` group.
The `alsa-utils` package provides the `alsa` service. When enabled, this service
saves and restores the state of ALSA (e.g. volume) at shutdown and boot,
respectively.
To allow use of software requiring PulseAudio, install the `apulse` package.
`apulse` provides part of the PulseAudio interface expected by applications,
translating calls to that interface into calls to ALSA. For details about using
`apulse`, consult [the project
README](https://github.com/i-rinat/apulse/blob/master/README.md).
## Configuration
The default sound card can be specified via ALSA configuration files or via
kernel module options.
To obtain information about the order of loaded sound card modules:
```
$ cat /proc/asound/modules
0 snd_hda_intel
1 snd_hda_intel
2 snd_usb_audio
```
To set a different card as the default, edit `/etc/asound.conf` or the per-user
configuration file `~/.asoundrc`:
```
defaults.ctl.card 2;
defaults.pcm.card 2;
```
or specify sound card module order in `/etc/modprobe.d/alsa.conf`:
```
options snd_usb_audio index=0
```
## Dmix
The `dmix` ALSA plugin allows playing sound from multiple sources. `dmix` is
enabled by default for soundcards which do not support hardware mixing. To
enable it for digital output, edit `/etc/asound.conf`:
```
pcm.dsp {
type plug
slave.pcm "dmix"
}
```

13
src/config/media/index.md Normal file
View File

@ -0,0 +1,13 @@
# Multimedia
## Audio setup
To setup audio on your EvolutionOS system you have to decide if you want to use
[PulseAudio](./pulseaudio.md), [PipeWire](./pipewire.md) or just
[ALSA](./alsa.md).
Some applications require PulseAudio, especially closed source programs, but
[PipeWire](./pipewire.md) provides a drop-in replacement for PulseAudio.
If [elogind](../session-management.md) is not enabled, it is necessary to be in
the `audio` group in order to have access to audio devices.

172
src/config/media/pipewire.md Normal file
View File

@ -0,0 +1,172 @@
# PipeWire
To use PipeWire, install the `pipewire` package.
[pipewire(1)](https://man.voidlinux.org/pipewire.1) should be started as a user.
Run the pipewire command in a terminal emulator in your session.
```
$ pipewire
```
When pipewire works as expected, use the autostarting mechanism of your desktop
environment or [startx](../graphical-session/xorg.md#startx). The `pipewire`
package ships [Desktop
Entry](https://specifications.freedesktop.org/desktop-entry-spec/latest/) files
for `pipewire` and `pipewire-pulse` in `/usr/share/applications`. If your
environment supports the [Desktop Application Autostart
Specification](https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html),
you can enable pipewire by symlinking the desktop files to the autostart
directory:
```
# ln -s /usr/share/applications/pipewire.desktop /etc/xdg/autostart/pipewire.desktop
```
## Session Management
In PipeWire, a session manager assumes responsibility for interconnecting media
sources and sinks as well as enforcing routing policy. Without a session
manager, PipeWire will not function. The reference
[`pipewire-media-session`](https://gitlab.freedesktop.org/pipewire/media-session)
was originally provided in the EvolutionOS `pipewire` package and configured to run by
default to satisfy this requirement. However, `pipewire-media-session` is
deprecated and the authors recommend using
[WirePlumber](https://pipewire.pages.freedesktop.org/wireplumber/) in its place.
Install the `wireplumber` package to use this session manager with PipeWire.
> If you have installed an earlier version of the EvolutionOS `pipewire` package, make
> sure to update your system to eliminate any stale system configuration that
> may attempt to launch `pipewire-media-session`. Users who previously overrode
> the system configuration to use `wireplumber`, *e.g.* by placing a custom
> `pipewire.conf` file in `/etc/pipewire` or `${XDG_CONFIG_HOME}/pipewire`, may
> wish to reconcile these overrides with `/usr/share/pipewire/pipewire.conf`
> installed by the most recent `pipewire` package. If the sole purpose of a
> prior override was to disable `pipewire-media-session`, deleting the custom
> configuration may be sufficient.
There are several methods for starting `wireplumber` alongside `pipewire`. If
your window manager or desktop environment auto-start mechanism is used to start
`pipewire`, it is recommended to use the same mechanism for starting
`wireplumber`. The `wireplumber` package includes a `wireplumber.desktop`
Desktop Entry file that may be useful in this situation.
> Be aware that `wireplumber` must launch *after* the `pipewire` executable. The
> Desktop Application Autostart Specification makes no provision for ordering of
> services started via Desktop Entry files. When relying on these files to
> launch `pipewire` and `wireplumber`, consult the documentation for your window
> manager or desktop environment to determine whether proper ordering of
> services can be achieved.
If proper ordering of separate `pipewire` and `wireplumber` services is
infeasible, it is possible to configure `pipewire` to launch the session manager
directly. This can be accomplished by running
```
# mkdir -p /etc/pipewire/pipewire.conf.d
# ln -s /usr/share/examples/wireplumber/10-wireplumber.conf /etc/pipewire/pipewire.conf.d/
```
for system configurations or, for per-user configurations, running
```
$ true "${XDG_CONFIG_HOME:=${HOME}/.config}"
$ mkdir -p "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d"
# ln -s /usr/share/examples/wireplumber/10-wireplumber.conf "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d/"
```
With either of these configurations, launching `pipewire` should be sufficient
to establish a working PipeWire session that uses `wireplumber` for session
management.
In its default configuration, WirePlumber requires an active [D-Bus
session](../session-management.md#d-bus). If your desktop environment or window
manager is configured to provide a D-Bus session as well as launch `pipewire`
and `wireplumber`, no further configuration should be required. Users wishing to
launch `pipewire` on its own, *e.g.*, in a `.xinitrc` script, may find it
necessary to configure `pipewire` to launch `wireplumber` directly and wrap the
`pipewire` invocation as
```
dbus-run-session pipewire
```
## PulseAudio replacement
Before starting `pipewire-pulse`, make sure that the PulseAudio service is
[disabled](../services/index.md#disabling-services) and that no other PulseAudio
server instance is running.
Start the PulseAudio server by running `pipewire-pulse` in a terminal emulator.
To check if the replacement is working correctly, use
[pactl(1)](https://man.voidlinux.org/pactl.1) (provided by the
`pulseaudio-utils` package):
```
$ pactl info
[...]
Server Name: PulseAudio (on PipeWire 0.3.18)
[...]
```
Once you confirmed that `pipewire-pulse` works as expected, it's recommended to
autostart it from the same place where you start PipeWire. Alternatively, the
`pipewire` configuration can be modified to launch `pipewire-pulse` directly:
```
# mkdir -p /etc/pipewire/pipewire.conf.d
# ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf /etc/pipewire/pipewire.conf.d/
```
for system configurations, or
```
$ true "${XDG_CONFIG_HOME:=${HOME}/.config}"
$ mkdir -p "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d"
# ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d/"
```
for per-user configurations.
## Bluetooth audio
For bluetooth audio to work, install the `libspa-bluetooth` package.
## ALSA integration
Install `alsa-pipewire`, then enable the PipeWire ALSA device and make it the
default:
```
# mkdir -p /etc/alsa/conf.d
# ln -s /usr/share/alsa/alsa.conf.d/50-pipewire.conf /etc/alsa/conf.d
# ln -s /usr/share/alsa/alsa.conf.d/99-pipewire-default.conf /etc/alsa/conf.d
```
## JACK replacement
Install `libjack-pipewire`.
Use [pw-jack(1)](https://man.voidlinux.org/pw-jack.1) to launch JACK clients
manually:
```
$ pw-jack <application>
```
Alternatively, override the library provided by `libjack` (see
[ld.so(8)](https://man.voidlinux.org/ld.so.8)). The following approach will work
on glibc-based systems:
```
# echo "/usr/lib/pipewire-0.3/jack" > /etc/ld.so.conf.d/pipewire-jack.conf
# ldconfig
```
## Troubleshooting
The PulseAudio replacement requires the
[`XDG_RUNTIME_DIR`](../session-management.html#xdg_runtime_dir) environment
variable to work correctly.

26
src/config/media/pulseaudio.md Normal file
View File

@ -0,0 +1,26 @@
# PulseAudio
Depending on which applications you use, you might need to provide PulseAudio
with a D-BUS session bus (e.g. via `dbus-run-session`) or a D-BUS system bus
(via the `dbus` service).
For applications which use ALSA directly and don't support PulseAudio, the
`alsa-plugins-pulseaudio` package can make them use PulseAudio through ALSA.
PulseAudio will automatically start when needed. If it is not starting
automatically, it can be started manually by invoking
[pulseaudio(1)](https://man.voidlinux.org/pulseaudio.1) from the terminal as
follows:
```
$ pulseaudio --daemonize=no --exit-idle-time=-1
```
On the other hand, PulseAudio can also end up being auto activated when it isn't
desired. To inhibit this behavior, the `autospawn` directive from
[pulse-client.conf(5)](https://man.voidlinux.org/pulse-client.conf.5) can be set
to `no`.
There are several methods of allowing PulseAudio to access to audio devices. The
simplest one is to add your user to the `audio` group. Alternatively, you can
use a session manager, like `elogind`.

61
src/config/media/sndio.md Normal file
View File

@ -0,0 +1,61 @@
# sndio
Install the `sndio` package and enable the
[sndiod(8)](https://man.voidlinux.org/sndiod.8) service.
## Configuration
The service can be configured by adding
[sndiod(8)](https://man.voidlinux.org/sndiod.8) flags to the `OPTS` variable in
the service configuration file (`/etc/sv/sndiod/conf`).
### Default device
[sndiod(8)](https://man.voidlinux.org/sndiod.8) uses the first ALSA device by
default. To use another ALSA device for sndio's default device `snd/0` add the
flags to use specific devices to the service configuration file.
```
# echo 'OPTS="-f rsnd/Speaker"' >/etc/sv/sndiod/conf
```
Use the `-f` flag to chooses a device by its ALSA device index or its ALSA
device name.
## Volume control
The master and per application volume controls are controlled with MIDI messages
by hardware or software.
[aucatctl(1)](https://man.voidlinux.org/aucatctl.1) is a tool specific to sndio
to send MIDI control messages to the
[sndiod(8)](https://man.voidlinux.org/sndiod.8) daemon. It can be found in the
`aucatctl` package.
## Application specific configurations
### Firefox
Firefox is built with sndio support and should work out of the box since version
71 if libsndio is installed and the `snd/0` device is available.
The following `about:config` changes are required for versions prior to 71 and
should be removed when using version 71 or later:
```
media.cubeb.backend;sndio
media.cubeb.sandbox;false
security.sandbox.content.read_path_whitelist;/home/<username>/.sndio/cookie
security.sandbox.content.write_path_whitelist;/home/<username>/.sndio/cookie
```
### OpenAL
libopenal comes with sndio support, but prioritizes ALSA over sndio by default.
You can configure this behavior per user in `~/.alsoftrc` or system wide in
`/etc/openal/alsoft.conf` by adding the following lines:
```
[general]
drivers = sndio
```

71
src/config/network-filesystems.md Normal file
View File

@ -0,0 +1,71 @@
# Network Filesystems
## NFS
### Mounting an NFS Share
To mount an NFS share, start by installing the `nfs-utils` and `sv-netmount`
packages.
Before mounting an NFS share, [enable](./services/index.md#enabling-services)
the `statd`, `rpcbind`, and `netmount` services. If the server supports `nfs4`,
the `statd` service isn't necessary.
To mount an NFS share:
```
# mount -t <mount_type> <host>:/path/to/sourcedir /path/to/destdir
```
`<mount_type>` should be `nfs4` if the server supports it, or `nfs` otherwise.
`<host>` can be either the hostname or IP address of the server.
Mounting options can be found in
[mount.nfs(8)](https://man.voidlinux.org/mount.nfs.8), while unmounting options
can be found in [umount.nfs(8)](https://man.voidlinux.org/umount.nfs.8).
For example, to connect `/volume` on a server at `192.168.1.99` to an existing
`/mnt/volume` directory on your local system:
```
# mount -t nfs 192.168.1.99:/volume /mnt/volume
```
To have the directory mounted when the system boots, add an entry to
[fstab(5)](https://man.voidlinux.org/fstab.5):
```
192.168.1.99:/volume /mnt/volume nfs rw,hard 0 0
```
Refer to [nfs(5)](https://man.voidlinux.org/nfs.5) for information about the
available mounting options.
### Setting up a server (NFSv4, Kerberos disabled)
To run an NFS server, start by installing the `nfs-utils` package.
Edit `/etc/exports` to add a shared volume:
```
/storage/foo *.local(rw,no_subtree_check,no_root_squash)
```
This line exports the `/storage/foo` directory to any host in the local domain,
with read/write access. For information about the `no_subtree_check` and
`no_root_squash` options, and available options more generally, refer to
[exports(5)](https://man.voidlinux.org/exports.5).
Finally, [enable](./services/index.md#enabling-services) the `rpcbind`, `statd`,
and `nfs-server` services.
This will start your NFS server. To check if the shares are working, use the
[showmount(8)](https://man.voidlinux.org/showmount.8) utility to check the NFS
server status:
```
# showmount -e localhost
```
You can use [nfs.conf(5)](https://man.voidlinux.org/nfs.conf.5) to configure
your server.

50
src/config/network/connman.md Normal file
View File

@ -0,0 +1,50 @@
# ConnMan
[ConnMan(8)](https://man.voidlinux.org/connman.8) is a daemon that manages
network connections, is designed to be slim and to use as few resources as
possible. The `connman` package contains the basic utilities to run ConnMan.
## Starting ConnMan
To enable the ConnMan daemon, first [disable](../services/index.md) any other
network managing services like [dhcpcd](./index.md#dhcpcd),
[wpa_supplicant](./wpa_supplicant.md), or `wicd`. These services all control
network interface configuration, and interfere with each other.
Finally, enable the `connmand` service.
## Configuring ConnMan
### ConnMan CLI
The `connman` package includes a command line tool,
[connmanctl(1)](https://man.voidlinux.org/connmanctl.1) to control network
settings. If you do not provide any commands, `connmanctl` starts as an
interactive shell.
Establishing a connection to an access point using the `connmanctl` interactive
shell might look as follows:
```
# connmanctl
> enable wifi
> agent on
> scan wifi
> services
> connect wifi_<uniqueid>
> exit
```
### ConnMan Front-End Tools
There are many other front-ends to ConnMan, including `connman-ui` for system
trays, `connman-gtk` for GTK, `cmst` for QT and `connman-ncurses` for ncurses
based UI.
## Preventing DNS overrides by ConnMan
Create `/etc/sv/connmand/conf` with the following content:
```
OPTS="--nodnsproxy"
```

92
src/config/network/firewalls.md Normal file
View File

@ -0,0 +1,92 @@
# Firewalls
## iptables
By default, the `iptables` package is installed on the base system. It provides
[iptables(8)/ip6tables(8)](https://man.voidlinux.org/iptables.8). The related
services use the `/etc/iptables/iptables.rules` and
`/etc/iptables/ip6tables.rules` ruleset files, which must be created by the
system administrator.
Two example rulesets are provided in the `/etc/iptables` directory:
`empty.rules` and `simple_firewall.rules`.
### Applying the rules at boot
To apply iptables rules at runit stage 1, install the `runit-iptables` package.
This adds a core-service which restores the `iptables.rules` and
`ip6tables.rules` rulesets.
Alternatively, to apply these rules at stage 2, add the following to
`/etc/rc.local`:
```
if [ -e /etc/iptables/iptables.rules ]; then
iptables-restore /etc/iptables/iptables.rules
fi
if [ -e /etc/iptables/ip6tables.rules ]; then
ip6tables-restore /etc/iptables/ip6tables.rules
fi
```
After rebooting, check the active firewall rules:
```
# iptables -L
# ip6tables -L
```
### Applying the rules at runtime
`iptables` comes with two runit services, `iptables` and `ip6tables`, to quickly
flush or restore the `iptables.rules` and `ip6tables.rules` rulesets. Once these
services are [enabled](../services/index.md#enabling-services), you can flush
the rulesets by downing the relevant service, e.g.:
```
# sv down iptables
```
and restore them by upping the relevant service, e.g.:
```
# sv up ip6tables
```
## nftables
`nftables` replaces `iptables`, `ip6tables`, `arptables` and `ebtables`
(collectively referred to as `xtables`). The [nftables
wiki](https://wiki.nftables.org/wiki-nftables/index.php/Main_Page) describes
[the main
differences](https://wiki.nftables.org/wiki-nftables/index.php/Main_differences_with_iptables)
from the `iptables` toolset.
To use `nftables`, install the `nftables` package, which provides
[nft(8)](https://man.voidlinux.org/nft.8). It also provides
[iptables-translate(8)/ip6tables-translate(8)](https://man.voidlinux.org/iptables-translate.8)
and
[iptables-restore-translate(8)/ip6tables-restore-translate(8)](https://man.voidlinux.org/iptables-restore-translate.8),
which convert `iptables` rules to `nftables` rules.
### Applying the rules at boot
To apply nftables rules at runit stage 1, install the `runit-nftables` package.
This adds a core-service which restores the ruleset in `/etc/nftables.conf`.
### Applying the rules at runtime
The `nftables` package provides the `nftables` service, which uses rules from
`/etc/nftables.conf`. Once you [enable](../services/index.md#enabling-service)
the `nftables` service, to load the rules, run:
```
# sv up nftables
```
To flush the rules, run:
```
# sv down nftables
```

71
src/config/network/index.md Normal file
View File

@ -0,0 +1,71 @@
# Network
Network configuration in EvolutionOS can be done in several ways. The default
installation comes with the [dhcpcd(8)](https://man.voidlinux.org/dhcpcd.8)
service enabled.
## Interface Names
Newer versions of [udev(7)](https://man.voidlinux.org/udev.7) no longer use the
traditional Linux naming scheme for interfaces (`eth0`, `eth1`, `wlan0`, ...).
This behavior can be reverted by adding `net.ifnames=0` to the [kernel
cmdline](../kernel.md#cmdline).
## Static Configuration
A simple way to configure a static network at boot is to add the necessary
[ip(8)](https://man.voidlinux.org/ip.8) commands to the `/etc/rc.local` file:
```
ip link set dev eth0 up
ip addr add 192.168.1.2/24 brd + dev eth0
ip route add default via 192.168.1.1
```
## Bridge Interfaces
To configure bridge interfaces at boot, the `/etc/rc.local` file can be used to
run [ip(8)](https://man.voidlinux.org/ip.8) commands to add the bridge `br0` and
set it as the master for the `eth0` interface as example:
```
ip link add name br0 type bridge
ip link set eth0 master br0
ip link set eth0 up
```
## dhcpcd
To run [dhcpcd(8)](https://man.voidlinux.org/dhcpcd.8) on all interfaces, enable
the `dhcpcd` service.
To run `dhcpcd` only on a specific interface, copy the `dhcpcd-eth0` service and
modify it to match your interface:
```
$ ip link show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
link/ether ff:ff:ff:ff:ff:ff brd ff:ff:ff:f
# cp -R /etc/sv/dhcpcd-eth0 /etc/sv/dhcpcd-enp3s0
# sed -i 's/eth0/enp3s0/' /etc/sv/dhcpcd-enp3s0/run
# ln -s /etc/sv/dhcpcd-enp3s0 /var/service/
```
For more information on configuring `dhcpcd`, refer to
[dhcpcd.conf(5)](https://man.voidlinux.org/dhcpcd.conf.5)
## Wireless
Before using wireless networking, use
[rfkill(8)](https://man.voidlinux.org/rfkill.8) to check whether the relevant
interfaces are soft- or hard-blocked.
EvolutionOS provides several ways to connect to wireless networks:
- [wpa_supplicant](./wpa_supplicant.md)
- [iwd](./iwd.md)
- [NetworkManager](./networkmanager.md)
- [ConnMan](./connman.md)

73
src/config/network/iwd.md Normal file
View File

@ -0,0 +1,73 @@
# IWD
[IWD](https://iwd.wiki.kernel.org/) (iNet Wireless Daemon) is a wireless daemon
for Linux that aims to replace [WPA supplicant](./wpa_supplicant.md).
## Installation
Install the `iwd` package and enable the `dbus` and `iwd` services.
## Usage
The command-line client [iwctl(1)](https://man.voidlinux.org/iwctl.1) can be
used to add, remove, and configure network connections. Commands can be passed
as arguments; when run without arguments, it provides an interactive session. To
list available commands, run `iwctl help`, or run `iwctl` and enter `help` at
the interactive prompt.
By default, only the root user and those in the `wheel` group have permission to
operate `iwctl`.
## Configuration
Configuration options and examples are described below. Consult the relevant
manual pages and the [upstream
documentation](https://iwd.wiki.kernel.org/networkconfigurationsettings) for
further information.
### Daemon configuration
The main configuration file is located in `/etc/iwd/main.conf`. If it does not
exist, you may create it. It is documented in
[iwd.config(5)](https://man.voidlinux.org/iwd.config.5).
### Network configuration
Network configuration, including examples, is documented in
[iwd.network(5)](https://man.voidlinux.org/iwd.network.5). IWD stores
information on known networks, and reads information on pre-provisioned networks
from network configuration files located in `/var/lib/iwd`; IWD monitors the
directory for changes. Network configuration filenames consist of the encoding
of the SSID followed by `.open`, `.psk`, or `.8021x` as determined by the
security type.
As an example, a basic configuration file for a WPA2/PSK secured network would
be called `<ssid>.psk`, and it would contain the plain text password:
```
[Security]
Passphrase=<password>
```
## Troubleshooting
By default, IWD will create and destroy the wireless interfaces (e.g. `wlan0`)
that it manages. This can interfere with `udevd`, which may attempt to rename
the interface using its rules for persistent network interface names. The
following messages may be printed to your screen as a symptom of this
interference:
```
[ 39.441723] udevd[1100]: Error changing net interface name wlan0 to wlp59s0: Device or resource busy
[ 39.442472] udevd[1100]: could not rename interface '3' from 'wlan0' to 'wlp59s0': Device or resource busy
```
A simple fix is to prevent IWD from manipulating the network interfaces in this
way by adding `UseDefaultInterface=true` to the `[General]` section of
`/etc/iwd/main.conf`.
An alternative approach is to disable the use of persistent network interface
names by `udevd`. This may be accomplished either by adding `net.ifnames=0` to
your kernel [cmdline](../kernel.md#cmdline) or by creating a symbolic link to
`/dev/null` at `/etc/udev/rules.d/80-net-name-slot.rules` to mask the renaming
rule. This alternative approach will affect the naming of all network devices.

46
src/config/network/networkmanager.md Normal file
View File

@ -0,0 +1,46 @@
# NetworkManager
[NetworkManager(8)](https://man.voidlinux.org/NetworkManager.8) is a daemon that
manages Ethernet, Wi-Fi, and mobile broadband network connections. Install the
`NetworkManager` package for the basic NetworkManager utilities.
## Starting NetworkManager
Before enabling the NetworkManager daemon, [disable](../services/index.md) any
other network management services, such as [dhcpcd](./index.md#dhcpcd),
[wpa_supplicant](./wpa_supplicant.md), or `wicd`. These services all control
network interface configuration, and will interfere with NetworkManager.
Also ensure that the `dbus` service is [enabled](../services/index.md) and
running. NetworkManager uses `dbus` to expose networking information and a
control interface to clients, and will fail to start without it.
Finally, enable the `NetworkManager` service.
## Configuring NetworkManager
Users of NetworkManager must belong to the `network` group.
The `NetworkManager` package includes a command line tool,
[nmcli(1)](https://man.voidlinux.org/nmcli.1), and a text-based user interface,
[nmtui(1)](https://man.voidlinux.org/nmtui.1), to control network settings.
There are many other front-ends to NetworkManager, including `nm-applet` for
system trays, `nm-plasma` for KDE Plasma, and a built-in network configuration
tool in GNOME.
## Eduroam with NetworkManager
Eduroam is a roaming service providing international, secure Internet access at
universities and other academic institutions. More information can be found
[here](https://eduroam.org/).
### Dependencies
Install the `python3-dbus` package.
### Installation
Download the correct eduroam_cat installer for your institution from
[here](https://cat.eduroam.org/) and execute it. It will provide a user
interface guiding you through the process.

87
src/config/network/wpa_supplicant.md Normal file
View File

@ -0,0 +1,87 @@
# wpa_supplicant
The `wpa_supplicant` package is installed by default on the base system. It
includes utilities to configure wireless interfaces and handle wireless security
protocols. To use wpa_supplicant, you will need to enable [the wpa_supplicant
service](#the-wpa_supplicant-service).
[wpa_supplicant(8)](https://man.voidlinux.org/wpa_supplicant.8) is a daemon that
manages wireless interfaces based on
[wpa_supplicant.conf(5)](https://man.voidlinux.org/wpa_supplicant.conf.5)
configuration files. An extensive overview of configuration options, including
examples, can be found in
`/usr/share/examples/wpa_supplicant/wpa_supplicant.conf`.
[wpa_passphrase(8)](https://man.voidlinux.org/wpa_passphrase.8) helps create
pre-shared keys for use in configuration files.
[wpa_cli(8)](https://man.voidlinux.org/wpa_cli.8) provides a CLI for managing
the `wpa_supplicant` daemon.
## WPA-PSK
To use WPA-PSK, generate a pre-shared key with
[wpa_passphrase(8)](https://man.voidlinux.org/wpa_passphrase.8) and append the
output to the relevant `wpa_supplicant.conf` file:
```
# wpa_passphrase <MYSSID> <passphrase> >> /etc/wpa_supplicant/wpa_supplicant-<device_name>.conf
```
## WPA-EAP
WPA-EAP is often used for institutional logins, notably eduroam. This does not
use PSK, but a password hash can be generated like this:
```
$ echo -n <passphrase> | iconv -t utf16le | openssl md4
```
## WEP
For WEP configuration, add the following lines to your device's
`wpa-supplicant.conf`:
```
network={
ssid="MYSSID"
key_mgmt=NONE
wep_key0="YOUR AP WEP KEY"
wep_tx_keyidx=0
auth_alg=SHARED
}
```
### The wpa_supplicant service
The `wpa_supplicant` service checks the following options in
`/etc/sv/wpa_supplicant/conf`:
- `OPTS`: Options to be passed to the service. Overrides any other options.
- `CONF_FILE`: Path to file to be used for configuration. Defaults to
`/etc/wpa_supplicant/wpa_supplicant.conf`.
- `WPA_INTERFACE`: Interface to be matched. May contain a wildcard; defaults to
all interfaces.
- `DRIVER`: Driver to use. See `wpa_supplicant -h` for available drivers.
If no `conf` file is found, the service searches for the following files in
`/etc/wpa_supplicant`:
- `wpa_supplicant-<interface>.conf`: If found, these files are bound to the
named interface.
- `wpa_supplicant.conf`: If found, this file is loaded and binds to all other
interfaces found.
Once you are satisfied with your configuration,
[enable](../services/index.md#enabling-services) the `wpa_supplicant` service.
### Using wpa_cli
When using `wpa_cli` to manage `wpa_supplicant` from the command line, be sure
to specify which network interface to use via the `-i` option, e.g.:
```
# wpa_cli -i wlp2s0
```
Not doing so can result in various `wpa_cli` commands (for example, `scan` and
`scan_results`) not producing the expected output.

34
src/config/openpgp.md Normal file
View File

@ -0,0 +1,34 @@
# GnuPG
EvolutionOS ships both GnuPG legacy (as `gnupg1`) and GnuPG stable (as `gnupg`).
## Smartcards
For using smartcards such as Yubikeys with GnuPG, there are two backends for
communicating with them through GnuPG: The internal CCID driver of GnuPG's
scdaemon, or the PC/SC driver.
## scdaemon with internal CCID driver
By default, scdaemon, which is required for using smartcards with GnuPG, uses
its internal CCID driver. For this to work, your smartcard needs to be one of
the smartcards in the udev rules
[here](https://github.com/void-linux/void-packages/blob/master/srcpkgs/gnupg/files/60-scdaemon.rules)
and you need to either be using elogind or be a member of the plugdev group. If
these two condition are fulfilled and you don't have pcscd running, `gpg
--card-status` should successfully print your current card status.
## scdaemon with pcscd backend
If you need to use pcscd for other reasons, run `echo disable-ccid >>
~/.gnupg/scdaemon.conf`. Now, assuming your pcscd setup works correctly, `gpg
--card-status` should print your card status.
# OpenPGP Card Tools
As an alternative to GnuPG with smartcards, EvolutionOS also ships
`openpgp-card-tools`, a Rust based utility not reliant on GnuPG. It requires
using `pcscd` for interacting with smart cards, so if you want to use it in
parallel with GnuPG, ou need to configure `scdaemon` to use the pcscd backend,
as described above in "[scdaemon with pcscd
backend](#scdaemon-with-pcscd-backend)".

16
src/config/package-documentation/index.md Normal file
View File

@ -0,0 +1,16 @@
# Package Documentation
The most common media for documentation in EvolutionOS are [manual
pages](./man.md).
Many packages contain documentation in other formats, like HTML. This
documentation can usually be found in a `/usr/share/doc/<package>` directory.
More extensive documentation may be split into separate `*-doc` packages, such
as `julia-doc`. This is often the case for programming languages, databases and
big software libraries.
In addition to documentation provided by upstream projects, packages may also
contain description of initial setup or usage specific to EvolutionOS, provided by
distribution contributors. It will be located in
`/usr/share/doc/<package>/README.voidlinux`.

77
src/config/package-documentation/man.md Normal file
View File

@ -0,0 +1,77 @@
# Manual Pages
Many EvolutionOS packages come with manual ('man') pages. The default installation
includes the [mandoc](https://mandoc.bsd.lv/) manpage toolset, via the `mdocml`
package.
The [man(1)](https://man.voidlinux.org/man.1) command can be used to show man
pages:
```
$ man chroot
```
Every man page belongs to a particular *section*:
- 1: User commands (Programs)
- 2: System calls
- 3: Library calls
- 4: Special files (devices)
- 5: File formats and configuration files
- 6: Games
- 7: Overview, conventions, and miscellaneous
- 8: System management commands
Refer to [man-pages(7)](https://man.voidlinux.org/man-pages.7) for details.
There are some man pages which have the same name, but are used in different
contexts, and are thus in a different section. You can specify which one to use
by including the section number in the call to `man`:
```
$ man 1 printf
```
`man` can be configured via [man.conf(5)](https://man.voidlinux.org/man.conf.5).
The `mandoc` toolset contains [apropos(1)](https://man.voidlinux.org/apropos.1),
which can be used to search for manual pages. `apropos` uses a database that can
be generated and updated with the
[makewhatis(8)](https://man.voidlinux.org/makewhatis.8) command:
```
# makewhatis
$ apropos chroot
chroot(1) - run command or interactive shell with special root directory
xbps-uchroot(1) - XBPS utility to chroot and bind mount with Linux namespaces
xbps-uunshare(1) - XBPS utility to chroot and bind mount with Linux user namespaces
chroot(2) - change root directory
```
The `mdocml` package provides a cron job to update the database daily,
`/etc/cron.daily/makewhatis`. You will need to install and enable a [cron
daemon](../cron.md) for this functionality to be activated.
Development and POSIX manuals are not installed by default, but are available
via the `man-pages-devel` and `man-pages-posix` packages.
## Localized manual pages
It is also possible to use localized man pages from packages which provide their
own as well as those provided by the `manpages-*` packages. However, this can
require some configuration.
### With mdocml
If `mdocml` is being used and the settings should be applied for all users, it
is necessary to add the relevant paths to
[man.conf(5)](https://man.voidlinux.org/man.conf.5). For example, German
speakers would add these two lines to their configuration file:
```
/usr/share/man/de
/usr/share/man/de.UTF-8
```
Alternatively, each user can export the `MANPATH` variable in their environment,
as explained in [man(1)](https://man.voidlinux.org/man.1).

35
src/config/php.md Normal file
View File

@ -0,0 +1,35 @@
# PHP
There are two ways to install PHP packages with XBPS:
1. Using the versioned packages (recommended).
2. Using the meta-packages.
## Versioned PHP Packages
It is generally recommended to use versioned PHP packages (e.g. `php8.1`,
`php8.1-apcu`, etc.) for most use cases as this ensures a consistent environment
on updates with minimal or no intervention required.
## PHP Meta-packages
In EvolutionOS, the `php` package is a meta-package that points to the latest upstream
PHP version. This convention is followed by all packages prefixed with `php-`,
such as `php-fpm`, as well as `xdebug` and `composer`. See [the `php`
template](https://github.com/void-linux/void-packages/blob/master/srcpkgs/php/template)
for a complete list. It is recommended to only use these meta-packages for
development purposes.
When using a PHP meta-package, be warned that updating may require manual
intervention if a new major PHP version has been added to the repository. As a
part of the version change, the configuration location will change to reflect
the new version. For example, upgrading from 8.0 to 8.1 would result in the
configuration path changing from `/etc/php8.0` to `/etc/php8.1`. Any
customizations that have been made need to be manually applied to the new
configuration directory.
`php-fpm` updates require special care since they include a runit service. In
this case, ensure that the new runit service is started and that applications
using the previous version of `php-fpm` can access the new `php-fpm` instance.
In particular, make sure any applications accessing the FPM instance have the
correct TCP/unix socket address.

26
src/config/power-management.md Normal file
View File

@ -0,0 +1,26 @@
# Power Management
## acpid
The `acpid` service for [acpid(8)](https://man.voidlinux.org/acpid.8) is
installed. ACPI events are handled by `/etc/acpi/handler.sh`, which uses
[zzz(8)](https://man.voidlinux.org/zzz.8) for suspend-to-RAM events.
## elogind
The `elogind` service is provided by the `elogind` package. By default,
[elogind(8)](https://man.voidlinux.org/elogind.8) listens for, and processes,
ACPI events related to lid-switch activation and the *power*, *suspend* and
*hibernate* keys. This will conflict with the `acpid` service if it is installed
and enabled. Either disable `acpid` when enabling `elogind`, or configure
`elogind` to `ignore` ACPI events in
[logind.conf(5)](https://man.voidlinux.org/logind.conf.5). There are several
configuration options, all starting with the keyword `Handle`, that should be
set to `ignore` to avoid interfering with `acpid`.
## Power Saving - tlp
Laptop battery life can be extended by using
[tlp(8)](https://man.voidlinux.org/tlp.8). To use it, install the `tlp` package,
and [enable](./services/index.md#enabling-services) the `tlp` service. Refer to
[the TLP documentation](https://linrunner.de/tlp/) for details.

114
src/config/print/index.md Normal file
View File

@ -0,0 +1,114 @@
# Printing
CUPS (Common Unix Printing System) is the supported mechanism for connecting to
printers on EvolutionOS.
As prerequisites, install the `cups` package and enable the `cupsd` service.
Wait until the service is marked available.
## Installing Printing Drivers
If the printer is being accessed over the network and supports PostScript or
PCL, CUPS alone should be sufficient. However, additional driver packages are
necessary for local printer support. The `cups-filters` package provides driver
support for CUPS.
Depending on the hardware in question, additional drivers may be necessary.
Some CUPS drivers contain proprietary or binary-only extensions. These are
available only in the nonfree repository, and sometimes only for specific
architectures.
### Driverless printing
Most modern network printers support printing driverlessly using the IPP
Everywhere standard. See <https://www.pwg.org/printers/> for a list of
self-certified printers supporting this standard. Even if a printer is not on
this list, there is still a high chance it is supported.
Do note that `cups-filters` is still required for driverless printing.
### Gutenprint drivers
Gutenprint provides support for many printers. These drivers are contained in
the `gutenprint` package.
### HP drivers
Printers from Hewlett-Packard require the `hplip` package.
Running the following command will guide you through the driver installation
process. The default configuration selections it suggests are typically
sufficient.
```
# hp-setup -i
```
### Brother drivers
For Brother printer support, install the foomatic drivers, which are contained
in the `foomatic-db` and `foomatic-db-nonfree` packages. Support for various
laser models is provided by the `brother-brlaser` package.
### Drivers for Epson Inkjet printers
Install the `epson-inkjet-printer-escpr` package for Epson Inkjet printers.
### Canon PIXMA/MAXIFY drivers
The `cnijfilter2` package contains drivers for various Canon PIXMA and MAXIFY
models. Please note that installing the driver package requires [enabling the
"nonfree" repository](../../xbps/repositories/index.md#nonfree).
## Configuring a New Printer
CUPS provides a web interface and command line tools that can be used to
configure printers. Additionally, various native GUI options are available and
may be better suited, depending on the use-case.
### Automatically
Printers with support for IPP Everywhere can be discovered and configured
automatically using [ZeroConf](http://www.zeroconf.org/). To enable this,
install the `avahi` and `nss-mdns` package and enable the `avahi-daemon`
service.
### Web interface
To configure the printer using the CUPS web interface, navigate to
<http://localhost:631> in a browser. Under the "Administration" tab, select
"Printers > Add Printer". When asked to log in, use an account that is in the
`lpadmin` group.
### Command line
The [lpadmin(8)](https://man.voidlinux.org/lpadmin.8) tool may be used to
configure a printer using the command line.
### Graphical interface
The `system-config-printer` package offers simple and robust configuration of
new printers. Install and invoke it:
```
# system-config-printer
```
Normally this tool requires root privileges. However, if you are using
PolicyKit, you can install the `cups-pk-helper` package to allow unprivileged
users to use `system-config-printer`.
While `system-config-printer` is shown here, your desktop environment may have a
native printer dialog, which may be found by consulting the documentation for
your DE.
## Troubleshooting
### USB printer not shown
The device URI can be found manually by running:
```
# /usr/lib/cups/backend/usb
```

53
src/config/rc-files.md Normal file
View File

@ -0,0 +1,53 @@
# rc.conf, rc.local and rc.shutdown
The files `/etc/rc.conf`, `/etc/rc.local` and `/etc/rc.shutdown` can be used to
configure certain parts of your EvolutionOS system. `rc.conf` is often configured by
`evolution-installer`.
## rc.conf
Sourced in runit stages 1 and 3. This file can be used to set variables,
including the following:
### KEYMAP
Specifies which keymap to use for the Linux console. Available keymaps are
listed in `/usr/share/kbd/keymaps`. For example:
```
KEYMAP=fr
```
For further details, refer to
[loadkeys(1)](https://man.voidlinux.org/loadkeys.1).
### HARDWARECLOCK
Specifies whether the hardware clock is set to UTC or local time.
By default this is set to `utc`. However, Windows sets the hardware clock to
local time, so if you are dual-booting with Windows, you need to either
configure Windows to use UTC, or set this variable to `localtime`.
For further details, refer to [hwclock(8)](https://man.voidlinux.org/hwclock.8).
### FONT
Specifies which font to use for the Linux console. Available fonts are listed in
`/usr/share/kbd/consolefonts`. For example:
```
FONT=eurlatgr
```
For further details, refer to [setfont(8)](https://man.voidlinux.org/setfont.8).
## rc.local
Sourced in runit stage 2. A shell script which can be used to specify
configuration to be done prior to login.
## rc.shutdown
Sourced in runit stage 3. A shell script which can be used to specify tasks to
be done during shutdown.

25
src/config/security/apparmor.md Normal file
View File

@ -0,0 +1,25 @@
# AppArmor
AppArmor is a mandatory access control mechanism (like SELinux). It can
constrain programs based on pre-defined or generated policy definitions.
EvolutionOS ships with some default profiles for several services, such as `dhcpcd` and
`wpa_supplicant`. Container runtimes such as LXC and podman integrate with
AppArmor for better security for container payloads.
To use AppArmor on a system, one must:
1. Install the `apparmor` package.
2. Set `apparmor=1 security=apparmor` on the kernel commandline.
To accomplish the second step, consult [the documentation on how to modify the
kernel cmdline](./../kernel.md#cmdline).
The `APPARMOR` variable in `/etc/default/apparmor` controls how profiles will be
loaded at boot, the value is set to `complain` by default and corresponds to
AppArmor modes (`disable`, `complain`, `enforce`).
AppArmor tools [aa-genprof(8)](https://man.voidlinux.org/aa-genprof.8) and
[aa-logprof(8)](https://man.voidlinux.org/aa-logprof.8) require either
configured [syslog](../services/logging.md) or a running
[auditd(8)](https://man.voidlinux.org/auditd.8) service.

8
src/config/security/index.md Normal file
View File

@ -0,0 +1,8 @@
# Security
There are several ways you can make your installation more secure. This section
explores some of them.
## Section Contents
- [AppArmor](./apparmor.md)

104
src/config/services/index.md Normal file
View File

@ -0,0 +1,104 @@
# Services and Daemons - dinit
EvolutionOS uses the dinit supervision suite to
run system services and daemons.
Some advantages of using dinit include:
- really damn fast, much improved upon the previously used runit
- very simple control panel interface
- drunner, a custom made facility to convert runit services to dinit services
If you don't need a program to be running constantly, but would like it to run
at regular intervals, you might like to consider using a [cron
daemon](../cron.md).
## Section Contents
- [Per-User Services](./user-services.md)
- [Logging](./logging.md)
## Service Directories
Each service managed by dinit has an associated *service file*.
Each service file contains various infomation about how to run the service.
For more infomation, visit [the manual](https://github.com/davmac314/dinit)
If a legacy runit service exists, it will be automatically converted on boot
### Configuring Services
For service simplicity and user-friendliness, we recommend you configure your services within the program itself
### Editing Services
To edit a service, first copy its service file to a different name.
Otherwise, [xbps-install(1)](https://man.voidlinux.org/xbps-install.1) can
overwrite the service file. Then, edit the new service file as needed.
Finally, the old service should be stopped and disabled, and the new one should
be started.
## Managing Services
### Basic Usage
To start, stop, restart or get the status of a service:
```
# dinitctl start <services>
# dinitctl stop <services>
# dinitctl restart <services>
# dinitctl status <services>
```
#### Enabling Services
EvolutionOS provides service files for most daemons in `/etc/dinit.d`.
To enable a service on a system, create a symlink to the service
file in `/etc/dinit.d/boot.d`:
```
# ln -s /etc/dinit.d/<service> /etc/dinit.d/boot.d/
```
You could alternativley use
```
# dinitctl enable <service>
```
Once a service is linked it will always start on boot and restart if it stops,
unless administratively downed.
#### Disabling Services
To disable a service, remove the symlink from the boot.d directory:
```
# rm /etc/dinit.d/boot.d/<service>
```
Or, you could simply run
```
# dinitctl disable <service>
```
#### Testing Services
To check if a service is working correctly when started by the service
supervisor, run it once before fully enabling it:
```
# dinitctl disable <service>
# dinitctl start <service>
```
If everything works, run
```
# dinitctl enable <service>
```

12
src/config/services/logging.md Normal file
View File

@ -0,0 +1,12 @@
# Logging
## Syslog
The default installation comes with a syslog daemon, but it is not enabled by
default. To enable it, create a service as documented in this [github page](# dinitctl start <service>)
for the deamon. The command is called syslogd.
### Other syslog daemons
The EvolutionOS repositories also include packages for `rsyslog`, `socklog` and
`metalog`.

1
src/config/services/user-services.md Normal file
View File

@ -0,0 +1 @@
# Per-User Services

64
src/config/session-management.md Normal file
View File

@ -0,0 +1,64 @@
# Session and Seat Management
Session and seat management is not necessary for every setup, but it can be used
to safely create temporary runtime directories, provide access to hardware
devices and multi-seat capabilities, and control system shutdown.
## D-Bus
D-Bus is an IPC (inter-process communication) mechanism used by userspace
software in Linux. D-Bus can provide a system bus and/or a session bus, the
latter being specific to a user session.
- To provide a system bus, you should [enable](./services/index.md) the `dbus`
service. This might require a system reboot to work properly.
- To provide a session bus, you can start a given program (usually a window
manager or interactive shell) with
[dbus-run-session(1)](https://man.voidlinux.org/dbus-run-session.1). Most
desktop environments, if launched through an adequate display manager, will
launch a D-Bus session themselves.
Note that some software assumes the presence of a system bus, while other
software assumes the presence of a session bus.
## elogind
[elogind(8)](https://man.voidlinux.org/elogind.8) manages user logins and system
power, as a standalone version of `systemd-logind`. elogind provides necessary
features for most desktop environments and Wayland compositors. It can also be
one of the mechanisms for rootless [Xorg](./graphical-session/xorg.md).
Please read the "[Power Management](./power-management.md)" section for things
to consider before installing elogind.
To make use of its features, install the `elogind` package and make sure the
[system D-Bus](#d-bus) is enabled. You might need to log out and in again.
If you're having any issues with elogind, [enable](./services/index.md) its
service, as waiting for a D-Bus activation can lead to issues.
## seatd
[seatd(1)](https://man.voidlinux.org/seatd.1) is a minimal seat management
daemon and an alternative to elogind primarily for [wlroots
compositors](./graphical-session/wayland.md#standalone-compositors).
To use it, install the `seatd` package and enable its service. If you want
non-root users to be able to access the seatd session, add them to the `_seatd`
group.
Note that, unlike elogind, seatd doesn't do anything besides managing seats.
## XDG_RUNTIME_DIR
`XDG_RUNTIME_DIR` is an environment variable defined by the [XDG Base Directory
Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
Its value sets the path to the base directory where programs should store
user-specific runtime files.
Install [elogind](#elogind) as your session manager to automatically set up
`XDG_RUNTIME_DIR`.
Alternatively, manually set the environment variable through the shell. Make
sure to create a dedicated user directory and set its permissions to `700`. A
good default location is `/run/user/$(id -u)`.

147
src/config/ssd.md Normal file
View File

@ -0,0 +1,147 @@
# Solid State Drives
Post installation, you will need to enable TRIM for solid state drives. You can
check which devices allow TRIM by running:
```
$ lsblk --discard
```
If the DISC-GRAN (discard granularity) and DISC-MAX (discard maximum bytes)
columns are non-zero, that means the block device has TRIM support. If your
solid state drive partition does not show TRIM support, please verify that you
chose a file system with TRIM support (ext4, Btrfs, F2FS, etc.). Note that F2FS
requires kernel 4.19 or above to support TRIM.
To run TRIM one-shot, you can run
[`fstrim(8)`](https://man.voidlinux.org/fstrim.8) manually. For example, if your
/ directory is on an SSD:
```
# fstrim /
```
To automate running TRIM, use cron or add the `discard` option to `/etc/fstab`.
## Periodic TRIM with cron
Add the following lines to `/etc/cron.weekly/fstrim`:
```
#!/bin/sh
fstrim /
```
Finally, make the script executable:
```
# chmod u+x /etc/cron.weekly/fstrim
```
## Continuous TRIM with fstab discard
You can use either continuous or periodic TRIM, but usage of continuous TRIM is
discouraged if you have an SSD that doesn't handle NCQ correctly. Refer to the
kernel
[blacklist](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/ata/libata-core.c?h=v5.8&id=bcf876870b95592b52519ed4aafcf9d95999bc9c#n3774).
Edit `/etc/fstab` and add the `discard` option to block devices that need TRIM.
For example, if `/dev/sda1` was an SSD partition, formatted as ext4, and mounted
at `/`:
```
/dev/sda1 / ext4 defaults,discard 0 1
```
## LVM
To enable TRIM for LVM's commands (`lvremove`, `lvreduce`, etc.), open
`/etc/lvm/lvm.conf`, uncomment the `issue_discards` option, and set it to `1`:
```
issue_discards=1
```
## LUKS
**Warning**: Before enabling discard for your LUKS partition, please be aware of
the [security
implications](https://wiki.archlinux.org/index.php/Dm-crypt/Specialties#Discard/TRIM_support_for_solid_state_drives_(SSD)).
To open an encrypted LUKS device and allow discards to pass through, open the
device with the `--allow-discards` option:
```
# cryptsetup luksOpen --allow-discards /dev/sdaX luks
```
### Non-root devices
Edit `/etc/crypttab` and set the `discard` option for devices on the SSD. For
example, if you have a LUKS device with the name `externaldrive1`, device
`/dev/sdb2`, and password `none`:
```
externaldrive1 /dev/sdb2 none luks,discard
```
### Root devices
If your root device is on LUKS, add `rd.luks.allow-discards` to
`CMDLINE_LINUX_DEFAULT`. In the case of GRUB, edit `/etc/default/grub`:
```
GRUB_CMDLINE_LINUX_DEFAULT="rd.luks.allow-discards"
```
### Verifying configuration
To verify that you have configured TRIM correctly for LUKS, run:
```
# dmsetup table /dev/mapper/crypt_dev --showkeys
```
If this command output contains the string `allow_discards`, you have
successfully enabled TRIM on your LUKS device.
## ZFS
Before running `trim` on a ZFS pool, ensure that all devices in the pool support
it:
```
# zpool get all | grep trim
```
If the pool allows `autotrim` (set `off` by default), you can `trim` the pool
periodically or automatically. To one-shot `trim` `yourpoolname`:
```
# zpool trim yourpoolname
```
### Periodic TRIM
Add the following lines to `/etc/cron.daily/ztrim`:
```
#!/bin/sh
zpool trim yourpoolname
```
Finally, make the script executable:
```
# chmod u+x /etc/cron.daily/ztrim
```
### Autotrim
To set autotrim for `yourpoolname`, run:
```
# zpool set autotrim=on yourpoolname
```

98
src/config/texlive.md Normal file
View File

@ -0,0 +1,98 @@
# TeX Live
In EvolutionOS, the `texlive-bin` package provides a basic TeX installation, including
the `tlmgr` program. Use `tlmgr` to install TeX packages and package collections
from CTAN mirrors. Install the `gnupg` package to allow `tlmgr` to verify TeX
packages.
The `texlive-bin` package contains the latest TeX Live version; however, earlier
versions, such as `texlive2018-bin`, are also available.
The `texlive` package and `texlive-*` packages are also available, and provide
TeX packages directly via xbps. TeX packages installed via those packages cannot
interact with TeX packages installed directly from CTAN (via `tlmgr`). For
example: `pdflatex` from `texlive-pdflatex` cannot be used to compile a TeX
document that uses a package installed via `tlmgr`; `tlmgr install pdflatex`
would be required for that.
## Configuring TeX Live
After installing TeX Live, update the value of `PATH`:
```
$ source /etc/profile
```
Check that `/opt/texlive/<year>/bin/x86_64-linux` (or
`/opt/texlive/<year>/bin/i386-linux`) is in your `PATH`:
```
$ echo $PATH
```
If required, change the global default paper size:
```
# tlmgr paper <letter|a4>
```
## Installing/Updating TeX packages
To install all available packages:
```
# tlmgr install scheme-full
```
To install specific packages, you can install the collection(s) including them.
To list the available collections:
```
$ tlmgr info collections
```
To see the list of files owned by a collection:
```
$ tlmgr info --list collection-<name>
```
To install the collection:
```
# tlmgr install collection-<name>
```
To install a standalone package, first check if the package exists:
```
$ tlmgr search --global <package>
```
and then install it:
```
# tlmgr install <package>
```
To find the package providing a particular file (for example, a font):
```
$ tlmgr search --file <filename> --global
```
To remove a package or a collection:
```
# tlmgr remove <package>
```
To update installed packages:
```
# tlmgr update --all
```
For a full description, check:
<https://www.tug.org/texlive/doc/tlmgr.html>

84
src/config/users-and-groups.md Normal file
View File

@ -0,0 +1,84 @@
# Users and Groups
The [useradd(8)](https://man.voidlinux.org/useradd.8),
[userdel(8)](https://man.voidlinux.org/userdel.8) and
[usermod(8)](https://man.voidlinux.org/usermod.8) commands are used to add,
delete and modify users respectively. The
[passwd(1)](https://man.voidlinux.org/passwd.1) command is used to change
passwords.
The [groupadd(8)](https://man.voidlinux.org/groupadd.8),
[groupdel(8)](https://man.voidlinux.org/groupdel.8) and
[groupmod(8)](https://man.voidlinux.org/groupmod.8) commands are used to add,
delete and modify groups respectively. The
[groups(1)](https://man.voidlinux.org/groups.1) command lists all groups a user
belongs to.
## Default shell
The default shell for a user can be changed with
[chsh(1)](https://man.voidlinux.org/chsh.1):
```
$ chsh -s <shell> <user_name>
```
`<shell>` must be the path to the shell as specified by `/etc/shells` or the
output of `chsh -l`, which provides a list of installed shells.
## sudo
[sudo(8)](https://man.voidlinux.org/sudo.8) is installed by default, but might
not be configured appropriately for your needs. It is only necessary to
configure sudo if you wish to use it.
Use [visudo(8)](https://man.voidlinux.org/visudo.8) as root to edit the
[sudoers(5)](https://man.voidlinux.org/sudoers.5) file.
To create a superuser, uncomment the line
```
#%wheel ALL=(ALL) ALL
```
and add users to the `wheel` group.
## Default Groups
EvolutionOS defines a number of groups by default.
| Group | Description |
|------------|---------------------------------------------------------------|
| `root` | Complete access to the system. |
| `bin` | Unused - present for historical reasons. |
| `sys` | Unused - present for historical reasons. |
| `kmem` | Ability to read from `/dev/mem` and `/dev/port`. |
| `wheel` | Elevated privileges for specific system administration tasks. |
| `tty` | Access to TTY-like devices: |
| | `/dev/tty*`, `/dev/pts*`, `/dev/vcs*`. |
| `tape` | Access to tape devices. |
| `daemon` | System daemons that need to write to files on disk. |
| `floppy` | Access to floppy drives. |
| `disk` | Raw access to `/dev/sd*` and `/dev/loop*`. |
| `lp` | Access to printers. |
| `dialout` | Access to serial ports. |
| `audio` | Access to audio devices. |
| `video` | Access to video devices. |
| `utmp` | Ability to write to `/var/run/utmp`, `/var/log/wtmp` |
| | and `/var/log/btmp`. |
| `adm` | Unused - present for historical reasons. This group was |
| | traditionally used for system monitoring, such as viewing |
| | files in `/var/log`. |
| `cdrom` | Access to CD devices. |
| `optical` | Access to DVD/CD-RW devices. |
| `mail` | Used by some mail packages, e.g. `dma`. |
| `storage` | Access to removable storage devices. |
| `scanner` | Ability to access scanners. |
| `network` | Unused - present for historical reasons. |
| `kvm` | Ability to use KVM for virtual machines, e.g. via QEMU. |
| `input` | Access to input devices: `/dev/mouse*`, `/dev/event*`. |
| `plugdev` | Access to pluggable devices. |
| `nogroup` | System daemons that don't need to own any files. |
| `usbmon` | Access to `/dev/usbmon*`. |
| `users` | Ordinary users. |
| `xbuilder` | To use xbps-uchroot(1) with `xbps-src`. |

10
src/contributing/evolution-docs/index.md Normal file
View File

@ -0,0 +1,10 @@
# Contributing To evolution-docs
The sources for this handbook are hosted in the
[evolution-docs](https://github.com/evolution-linux/evolution-docs) repository on
[GitHub](https://github.com). If you would like to make a contribution, please
read about [the purpose of the Handbook](../../about/about-this-handbook.md),
follow our [style
guide](https://github.com/evolution-linux/evolution-docs/blob/master/CONTRIBUTING.md#style-guide)
and [submit a pull
request](https://github.com/evolution-linux/evolution-docs/blob/master/CONTRIBUTING.md#submitting-changes).

35
src/contributing/index.md Normal file
View File

@ -0,0 +1,35 @@
# Contributing
There's more to running a distribution than just writing code.
To contribute to the EvolutionOS packages repository, start by reading the
[CONTRIBUTING](https://github.com/evolution-linux/evolution-packages/blob/master/CONTRIBUTING.md)
document in the evolution-packages GitHub repository.
To contribute to this Handbook, read
[CONTRIBUTING](https://github.com/evolution-linux/evolution-docs/blob/master/CONTRIBUTING.md)
in the evolution-docs repository.
If you have any questions, feel free to email Tracker-Friendly at jliwin98@danwin1210.de
## Usage Statistics
If you would like to contribute usage reports, the
[PopCorn](https://github.com/the-maldridge/popcorn) program reports installation
statistics back to the Void project. These statistics are purely opt-in -
PopCorn is *not* installed or enabled by default on any Void or EvolutionOS systems.
Additionally, PopCorn requires that port 8001 not be blocked on your system.
*PopCorn* only reports which packages are installed, their version, and the host
CPU architecture (the output of `xuname`). This does not report which services
are enabled, or any other personal information. Individual systems are tracked
persistently by a random (client-generated) UUID, to ensure that each system is
only counted once in each 24-hour sampling period.
The data collected by *PopCorn* is available to view at
<http://popcorn.voidlinux.org>
### Setting up PopCorn
First, install the `PopCorn` package. Then, enable the `popcorn` service, which
will attempt to report statistics once per day.

3
src/installation/guides/arm-devices/index.md Normal file
View File

@ -0,0 +1,3 @@
# ARM Devices
ARM is not supported currently. A future update may add ARM support.

3
src/installation/guides/arm-devices/platforms.md Normal file
View File

@ -0,0 +1,3 @@
# Supported Platforms
ARM Is not currently supported.

288
src/installation/guides/chroot.md Normal file
View File

@ -0,0 +1,288 @@
# Installation via chroot (x86/x86_64/aarch64)
This guide details the process of manually installing EvolutionOS via a chroot on an
x86, x86_64 or aarch64 architecture. It is assumed that you have a familiarity
with Linux, but not necessarily with installing a Linux system via a chroot.
This guide can be used to create a "typical" setup, using a single partition on
a single SATA/IDE/USB disk. Each step may be modified to create less typical
setups, such as [full disk encryption](./fde.md).
EvolutionOS provides two options for bootstrapping the new installation. The **XBPS
method** uses the [XBPS Package Manager](../../xbps/index.md) running on a host
operating system to install the base system. The **ROOTFS method** installs the
base system by unpacking a ROOTFS tarball.
The **XBPS method** requires that the host operating system have XBPS installed.
This may be an existing installation of EvolutionOS, an official [live
image](../live-images/prep.md), or any Linux installation running a [statically
linked XBPS](../../xbps/troubleshooting/static.md).
## Prepare Filesystems
[Partition your disks](../live-images/partitions.md) and format them using
[mke2fs(8)](https://man.voidlinux.org/mke2fs.8),
[mkfs.xfs(8)](https://man.voidlinux.org/mkfs.xfs.8),
[mkfs.btrfs(8)](https://man.voidlinux.org/mkfs.btrfs.8) or whatever tools are
necessary for your filesystem(s) of choice.
[mkfs.vfat(8)](https://man.voidlinux.org/mkfs.vfat.8) is also available to
create FAT32 partitions. However, due to restrictions associated with FAT
filesystems, it should only be used when no other filesystem is suitable (such
as for the EFI System Partition).
[cfdisk(8)](https://man.voidlinux.org/cfdisk.8) and
[fdisk(8)](https://man.voidlinux.org/fdisk.8) are available on the live images
for partitioning, but you may wish to use
[gdisk(8)](https://man.voidlinux.org/gdisk.8) (from the package `gptfdisk`) or
[parted(8)](https://man.voidlinux.org/parted.8) instead.
For a UEFI booting system, make sure to create an EFI System Partition (ESP).
The ESP should have the partition type "EFI System" (code `EF00`) and be
formatted as FAT32 using [mkfs.vfat(8)](https://man.voidlinux.org/mkfs.vfat.8).
If you're unsure what partitions to create, create a 1GB partition of type "EFI
System" (code `EF00`), then create a second partition of type "Linux Filesystem"
(code `8300`) using the remainder of the drive.
Format these partitions as FAT32 and ext4, respectively:
```
# mkfs.vfat /dev/sda1
# mkfs.ext4 /dev/sda2
```
### Create a New Root and Mount Filesystems
This guide will assume the new root filesystem is mounted on `/mnt`. You may
wish to mount it elsewhere.
If using UEFI, mount the EFI System Partition as `/mnt/boot/efi`.
For example, if `/dev/sda2` is to be mounted as `/` and `dev/sda1` is the EFI
System Partition:
```
# mount /dev/sda2 /mnt/
# mkdir -p /mnt/boot/efi/
# mount /dev/sda1 /mnt/boot/efi/
```
Initialize swap space, if desired, using
[mkswap(8)](https://man.voidlinux.org/mkswap.8).
## Base Installation
Follow only one of the two following subsections.
If on aarch64, it will be necessary to install a kernel package in addition to
`base-system`. For example, `linux` is a kernel package that points to the
latest stable kernel packaged by EvolutionOS.
### The XBPS Method
Select a [mirror](../../xbps/repositories/mirrors/index.md) and **use the**
[**appropriate URL**](../../xbps/repositories/index.md#the-main-repository) for
the type of system you wish to install. For simplicity, save this URL to a shell
variable. A glibc installation, for example, would use:
```
# REPO=https://evolution-linux.github.io/pkg
# REPO=https://repo-default.voidlinux.org/current
```
XBPS also needs to know what architecture is being installed. Available options
are `x86_64`, `x86_64-musl`, `i686` for PC architecture computers and `aarch64`.
For example:
```
# ARCH=x86_64
```
This architecture must be compatible with your current operating system, but
does not need to be the same. If your host is running an x86_64 operating
system, any of the three architectures can be installed (whether the host is
musl or glibc), but an i686 host can only install i686 distributions.
Copy the RSA keys from the installation medium to the target root directory:
```
# mkdir -p /mnt/var/db/xbps/keys
# cp /var/db/xbps/keys/* /mnt/var/db/xbps/keys/
```
Use [xbps-install(1)](https://man.voidlinux.org/xbps-install.1) to bootstrap the
installation by installing the `base-system` metapackage:
```
# XBPS_ARCH=$ARCH xbps-install -S -r /mnt -R "$REPO" base-system
```
## Configuration
With the exception of the section "Install base-system (ROOTFS method only)",
the remainder of this guide is common to both the XBPS and ROOTFS installation
methods.
### Entering the Chroot
[xchroot(1)](https://man.voidlinux.org/xchroot.1) (from `xtools`) can be used to
set up and enter the chroot. Alternatively, this can be [done
manually](../../config/containers-and-vms/chroot.md#manual-method).
```
# xchroot /mnt /bin/bash
```
### Installation Configuration
Specify the hostname in `/etc/hostname`. Go through the options in
[`/etc/rc.conf`](../../config/rc-files.md#rcconf). If installing a glibc
distribution, edit `/etc/default/libc-locales`, uncommenting desired
[locales](../../config/locales.md).
[nvi(1)](https://man.voidlinux.org/nvi.1) is available in the chroot, but you
may wish to install your preferred text editor at this time.
For glibc builds, generate locale files with:
```
[xchroot /mnt] # xbps-reconfigure -f glibc-locales
```
### Set a Root Password
[Configure at least one super user account](../../config/users-and-groups.md).
Other user accounts can be configured later, but there should either be a root
password, or a new user account with [sudo(8)](https://man.voidlinux.org/sudo.8)
privileges.
To set a root password, run:
```
[xchroot /mnt] # passwd
```
### Configure fstab
The [fstab(5)](https://man.voidlinux.org/fstab.5) file can be automatically
generated from currently mounted filesystems by copying the file `/proc/mounts`:
```
[xchroot /mnt] # cp /proc/mounts /etc/fstab
```
Remove lines in `/etc/fstab` that refer to `proc`, `sys`, `devtmpfs` and `pts`.
Replace references to `/dev/sdXX`, `/dev/nvmeXnYpZ`, etc. with their respective
UUID, which can be found by running
[blkid(8)](https://man.voidlinux.org/blkid.8). Referring to filesystems by their
UUID guarantees they will be found even if they are assigned a different name at
a later time. In some situations, such as booting from USB, this is absolutely
essential. In other situations, disks will always have the same name unless
drives are physically added or removed. Therefore, this step may not be strictly
necessary, but is almost always recommended.
Change the last zero of the entry for `/` to `1`, and the last zero of every
other line to `2`. These values configure the behaviour of
[fsck(8)](https://man.voidlinux.org/fsck.8).
For example, the partition scheme used throughout previous examples yields the
following `fstab`:
```
/dev/sda1 /boot/efi vfat rw,relatime,[...] 0 0
/dev/sda2 / ext4 rw,relatime 0 0
```
The information from `blkid` results in the following `/etc/fstab`:
```
UUID=6914[...] /boot/efi vfat rw,relatime,[...] 0 2
UUID=dc1b[...] / ext4 rw,relatime 0 1
```
Note: The output of `/proc/mounts` will have a single space between each field.
The columns are aligned here for readability.
Add an entry to mount `/tmp` in RAM:
```
tmpfs /tmp tmpfs defaults,nosuid,nodev 0 0
```
If using swap space, add an entry for any swap partitions:
```
UUID=1cb4[...] swap swap rw,noatime,discard 0 0
```
## Installing GRUB
Use
[grub-install](https://www.gnu.org/software/grub/manual/grub/html_node/Installing-GRUB-using-grub_002dinstall.html)
to install GRUB onto your boot disk.
**On a BIOS computer**, install the package `grub`, then run `grub-install
/dev/sdX`, where `/dev/sdX` is the drive (not partition) that you wish to
install GRUB to. For example:
```
[xchroot /mnt] # xbps-install grub
[xchroot /mnt] # grub-install /dev/sda
```
**On a UEFI computer**, install either `grub-x86_64-efi`, `grub-i386-efi` or
`grub-arm64-efi`, depending on your architecture, then run `grub-install`,
optionally specifying a bootloader label (this label may be used by your
computer's firmware when manually selecting a boot device):
```
[xchroot /mnt] # xbps-install grub-x86_64-efi
[xchroot /mnt] # grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id="Void"
```
### Troubleshooting GRUB installation
If EFI variables are not available, add the option `--no-nvram` to the
`grub-install` command.
#### Installing on removable media or non-compliant UEFI systems
Unfortunately, not all systems have a fully standards compliant UEFI
implementation. In some cases, it is necessary to "trick" the firmware into
booting by using the default fallback location for the bootloader instead of a
custom one. In that case, or if installing onto a removable disk (such as USB),
add the option `--removable` to the `grub-install` command.
Alternatively, use [mkdir(1)](https://man.voidlinux.org/mkdir.1) to create the
`/boot/efi/EFI/boot` directory and copy the installed GRUB executable, usually
located in `/boot/efi/EFI/Void/grubx64.efi` (its location can be found using
[efibootmgr(8)](https://man.voidlinux.org/efibootmgr.8)), into the new folder:
```
[xchroot /mnt] # mkdir -p /boot/efi/EFI/boot
[xchroot /mnt] # cp /boot/efi/EFI/Void/grubx64.efi /boot/efi/EFI/boot/bootx64.efi
```
## Finalization
Use [xbps-reconfigure(1)](https://man.voidlinux.org/xbps-reconfigure.1) to
ensure all installed packages are configured properly:
```
[xchroot /mnt] # xbps-reconfigure -fa
```
This will make [dracut(8)](https://man.voidlinux.org/dracut.8) generate an
initramfs, and will make GRUB generate a working configuration.
At this point, the installation is complete. Exit the chroot and reboot your
computer:
```
[xchroot /mnt] # exit
# umount -R /mnt
# shutdown -r now
```
After booting into your evolutionOS installation for the first time, [perform a system
update](../../xbps/index.md#updating).

289
src/installation/guides/fde.md Normal file
View File

@ -0,0 +1,289 @@
# Full Disk Encryption
**Warning**: Your drive's block device and other information may be different,
so make sure it is correct.
## Partitioning
Boot a live image and login.
Create a single physical partition on the disk using
[cfdisk](https://man.voidlinux.org/cfdisk), marking it as bootable. For an MBR
system, the partition layout should look like the following.
```
# fdisk -l /dev/sda
Disk /dev/sda: 48 GiB, 51539607552 bytes, 100663296 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x4d532059
Device Boot Start End Sectors Size Id Type
/dev/sda1 * 2048 100663295 100661248 48G 83 Linux
```
UEFI systems will need the disk to have a GPT disklabel and an EFI system
partition. The required size for this may vary depending on needs, but 100M
should be enough for most cases. For an EFI system, the partition layout should
look like the following.
```
# fdisk -l /dev/sda
Disk /dev/sda: 48 GiB, 51539607552 bytes, 100663296 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: EE4F2A1A-8E7F-48CA-B3D0-BD7A01F6D8A0
Device Start End Sectors Size Type
/dev/sda1 2048 264191 262144 128M EFI System
/dev/sda2 264192 100663262 100399071 47.9G Linux filesystem
```
## Encrypted volume configuration
[Cryptsetup](https://man.voidlinux.org/cryptsetup.8) defaults to LUKS2, yet GRUB
releases before 2.06 only had support for LUKS1.
LUKS2 is only partially supported by GRUB; specifically, only the PBKDF2 key
derivation function is
[implemented](https://git.savannah.gnu.org/cgit/grub.git/commit/?id=365e0cc3e7e44151c14dd29514c2f870b49f9755),
which is *not* the default KDF used with LUKS2, that being Argon2i ([GRUB Bug
59409](https://savannah.gnu.org/bugs/?59409)). LUKS encrypted partitions using
Argon2i (as well as the other KDF) can *not* be decrypted. For that reason, this
guide only recommends LUKS1 be used.
Keep in mind the encrypted volume will be `/dev/sda2` on EFI systems, since
`/dev/sda1` is taken up by the EFI partition.
```
# cryptsetup luksFormat --type luks1 /dev/sda1
WARNING!
========
This will overwrite data on /dev/sda1 irrevocably.
Are you sure? (Type uppercase yes): YES
Enter passphrase:
Verify passphrase:
```
Once the volume is created, it needs to be opened. Replace `voidvm` with an
appropriate name. Again, this will be `/dev/sda2` on EFI systems.
```
# cryptsetup luksOpen /dev/sda1 voidvm
Enter passphrase for /dev/sda1:
```
Once the LUKS container is opened, create the LVM volume group using that
partition.
```
# vgcreate voidvm /dev/mapper/voidvm
Volume group "voidvm" successfully created
```
There should now be an empty volume group named `voidvm`.
Next, logical volumes need to be created for the volume group. For this example,
I chose 10G for `/`, 2G for `swap`, and will assign the rest to `/home`.
```
# lvcreate --name root -L 10G voidvm
Logical volume "root" created.
# lvcreate --name swap -L 2G voidvm
Logical volume "swap" created.
# lvcreate --name home -l 100%FREE voidvm
Logical volume "home" created.
```
Next, create the filesystems. The example below uses XFS as a personal
preference of the author. Any filesystem [supported by
GRUB](https://www.gnu.org/software/grub/manual/grub/grub.html#Features) will
work.
```
# mkfs.xfs -L root /dev/voidvm/root
meta-data=/dev/voidvm/root isize=512 agcount=4, agsize=655360 blks
...
# mkfs.xfs -L home /dev/voidvm/home
meta-data=/dev/voidvm/home isize=512 agcount=4, agsize=2359040 blks
...
# mkswap /dev/voidvm/swap
Setting up swapspace version 1, size = 2 GiB (2147479552 bytes)
```
## System installation
Next, setup the chroot and install the base system.
```
# mount /dev/voidvm/root /mnt
# mkdir -p /mnt/home
# mount /dev/voidvm/home /mnt/home
```
On a UEFI system, the EFI system partition also needs to be mounted.
```
# mkfs.vfat /dev/sda1
# mkdir -p /mnt/boot/efi
# mount /dev/sda1 /mnt/boot/efi
```
Copy the RSA keys from the installation medium to the target root directory:
```
# mkdir -p /mnt/var/db/xbps/keys
# cp /var/db/xbps/keys/* /mnt/var/db/xbps/keys/
```
Before we enter the chroot to finish up configuration, we do the actual install.
Do not forget to use the [appropriate repository
URL](../../xbps/repositories/index.md#the-main-repository) for the type of
system you wish to install.
```
# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system lvm2 cryptsetup grub
[*] Updating `https://repo-default.voidlinux.org/current/x86_64-repodata' ...
x86_64-repodata: 1661KB [avg rate: 2257KB/s]
130 packages will be downloaded:
...
```
UEFI systems will have a slightly different package selection. The installation
command for a UEFI system will be as follows.
```
# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system cryptsetup grub-x86_64-efi lvm2
```
When it's done, we can enter the chroot with
[`xchroot(1)`](https://man.voidlinux.org/xchroot.1) (from `xtools`) and finish
up the configuration. Alternatively, entering the chroot can be [done
manually](../../config/containers-and-vms/chroot.md#manual-method).
```
# xchroot /mnt
[xchroot /mnt] # chown root:root /
[xchroot /mnt] # chmod 755 /
[xchroot /mnt] # passwd root
[xchroot /mnt] # echo voidvm > /etc/hostname
```
and, for glibc systems only:
```
[xchroot /mnt] # echo "LANG=en_US.UTF-8" > /etc/locale.conf
[xchroot /mnt] # echo "en_US.UTF-8 UTF-8" >> /etc/default/libc-locales
[xchroot /mnt] # xbps-reconfigure -f glibc-locales
```
### Filesystem configuration
The next step is editing `/etc/fstab`, which will depend on how you configured
and named your filesystems. For this example, the file should look like this:
```
# <file system> <dir> <type> <options> <dump> <pass>
tmpfs /tmp tmpfs defaults,nosuid,nodev 0 0
/dev/voidvm/root / xfs defaults 0 0
/dev/voidvm/home /home xfs defaults 0 0
/dev/voidvm/swap swap swap defaults 0 0
```
UEFI systems will also have an entry for the EFI system partition.
```
/dev/sda1 /boot/efi vfat defaults 0 0
```
### GRUB configuration
Next, configure GRUB to be able to unlock the filesystem. Add the following line
to `/etc/default/grub`:
```
GRUB_ENABLE_CRYPTODISK=y
```
Next, the kernel needs to be configured to find the encrypted device. First,
find the UUID of the device.
```
[xchroot /mnt] # blkid -o value -s UUID /dev/sda1
135f3c06-26a0-437f-a05e-287b036440a4
```
Edit the `GRUB_CMDLINE_LINUX_DEFAULT=` line in `/etc/default/grub` and add
`rd.lvm.vg=voidvm rd.luks.uuid=<UUID>` to it. Make sure the UUID matches the one
for the `sda1` device found in the output of the
[blkid(8)](https://man.voidlinux.org/blkid.8) command above. This will be
`/dev/sda2` on EFI systems.
## LUKS key setup
And now to avoid having to enter the password twice on boot, a key will be
configured to automatically unlock the encrypted volume on boot. First, generate
a random key.
```
[xchroot /mnt] # dd bs=1 count=64 if=/dev/urandom of=/boot/volume.key
64+0 records in
64+0 records out
64 bytes copied, 0.000662757 s, 96.6 kB/s
```
Next, add the key to the encrypted volume.
```
[xchroot /mnt] # cryptsetup luksAddKey /dev/sda1 /boot/volume.key
Enter any existing passphrase:
```
Change the permissions to protect the generated key.
```
[xchroot /mnt] # chmod 000 /boot/volume.key
[xchroot /mnt] # chmod -R g-rwx,o-rwx /boot
```
This keyfile also needs to be added to `/etc/crypttab`. Again, this will be
`/dev/sda2` on EFI systems.
```
voidvm /dev/sda1 /boot/volume.key luks
```
And then the keyfile and `crypttab` need to be included in the initramfs. Create
a new file at `/etc/dracut.conf.d/10-crypt.conf` with the following line:
```
install_items+=" /boot/volume.key /etc/crypttab "
```
## Complete system installation
Next, install the boot loader to the disk.
```
[xchroot /mnt] # grub-install /dev/sda
```
Ensure an initramfs is generated:
```
[xchroot /mnt] # xbps-reconfigure -fa
```
Exit the `chroot`, unmount the filesystems, and reboot the system.
```
[xchroot /mnt] # exit
# umount -R /mnt
# reboot
```

10
src/installation/guides/index.md Normal file
View File

@ -0,0 +1,10 @@
# Advanced Installation Guides
This section contains guides for more specific or complex use-cases.
## Section Contents
- [Installing evolutionOS via chroot (x86 or x86_64)](./chroot.md)
- [Installing evolutionOS with Full Disk Encryption](./fde.md)
- [Installing evolutionOS on a ZFS Root](./zfs.md)
- [ARM Devices](./arm-devices/index.md)

179
src/installation/guides/zfs.md Normal file
View File

@ -0,0 +1,179 @@
# Installing EvolutionOS on a ZFS Root
Because the EvolutionOS installer does not support ZFS, it is necessary to install via
chroot. Aside from a few caveats regarding bootloader and initramfs support,
installing EvolutionOS on a ZFS root filesystem is not significantly different from any
other advanced installation. [ZFSBootMenu](https://zfsbootmenu.org) is a
bootloader designed from the ground up to support booting Linux distributions
directly from a ZFS pool. However, it is also possible to use traditional
bootloaders with a ZFS root.
## ZFSBootMenu
ZFSBootMenu supports native ZFS encryption, offers a convenient recovery
environment that can be used to clone prior snapshots or perform advanced
manipulation in a pre-boot environment, and will support booting from any
pool that is importable by modern ZFS drivers. The ZFSBootMenu documentation
offers, among other content, several [step-by-step guides](https://docs.zfsbootmenu.org/en/latest/guides/void-linux.html) for installing a EvolutionOS system from scratch. The [UEFI guide](https://docs.zfsbootmenu.org/en/latest/guides/void-linux/uefi.html)
describes the procedure of bootstrapping a EvolutionOS system for modern systems. For
legacy BIOS systems, the [syslinux guide](https://docs.zfsbootmenu.org/en/latest/guides/void-linux/syslinux-mbr.html)provides comparable instructions.
## Traditional bootloaders
For those that wish to forego ZFSBootMenu, it is possible to bootstrap a EvolutionOS
system with another bootloader. To avoid unnecessary complexity, systems that
use bootloaders other than ZFSBootMenu should plan to use a separate `/boot`
that is located on an ext4 or xfs filesystem.
### Installation media
Installing EvolutionOS to a ZFS root requires an installation medium with ZFS drivers.
It is possible to build a custom image from the official
[evolution-installer](https://centrifuge.hectabit.org/evolutionos/evolution-installer) repository by providing
the command-line option `-p zfs` to the `mklive.sh` script. However, for
`x86_64` systems, it may be more convenient to fetch a pre-built
[hrmpf](https://github.com/leahneukirchen/hrmpf/releases) image. These images,
maintained by the Void Linux projects, are extensions of the standard Void live
images that include pre-compiled ZFS modules in addition to other useful tools.
To use these, add https://hectabit.org/evolutionos/pkg to the repository list.
### Partition disks
After booting a live image with ZFS support, [partition your
disks](../live-images/partitions.md). The considerations in the partitioning
guide apply to ZFS installations as well, except that
- The boot partition should be considered necessary unless you intend to use
`gummiboot`, which expects that your EFI system partition will be mounted at
`/boot`. (This alternative configuration will not be discussed here.)
- Aside from any EFI system partition, GRUB BIOS boot partition, swap or boot
partitions, the remainder of the disk should typically be a single partition
with type code `BF00` that will be dedicated to a single ZFS pool. There is
no benefit to creating separate ZFS pools on a single disk.
As needed, format the EFI system partition using
[mkfs.vfat(8)](https://man.voidlinux.org/mkfs.vfat.8) and the the boot partition
using [mke2fs(8)](https://man.voidlinux.org/mke2fs.8) or
[mkfs.xfs(8)](https://man.voidlinux.org/mkfs.xfs.8). Initialize any swap space
using [mkswap(8)](https://man.voidlinux.org).
> It is possible to put Linux swap space on a ZFS zvol, although there may be a
> risk of deadlocking the kernel when under high memory pressure. This guide
> takes no position on the matter of swap space on a zvol. However, if you wish
> to use suspension-to-disk (hibernation), note that the kernel is not capable
> of resuming from memory images stored on a zvol. You will need a dedicated
> swap partition to use hibernation. Apart from this caveat, there are no
> special considerations required to resume a suspended image when using a ZFS
> root.
### Create a ZFS pool
Create a ZFS pool on the partition created for it using
[zpool(8)](https://man.voidlinux.org/zpool.8). For example, to create a pool on
`/dev/disk/by-id/wwn-0x5000c500deadbeef-part3`:
```
# zpool create -f -o ashift=12 \
-O compression=lz4 \
-O acltype=posixacl \
-O xattr=sa \
-O relatime=on \
-o autotrim=on \
-m none zroot /dev/disk/by-id/wwn-0x5000c500deadbeef-part3
```
Adjust the pool (`-o`) and filesystem (`-O`) options as desired, and replace the
partition identifier `wwn-0x5000c500deadbeef-part3` with that of the actual
partition to be used.
> When adding disks or partitions to ZFS pools, it is generally advisable to
> refer to them by the symbolic links created in `/dev/disk/by-id` or (on UEFI
> systems) `/dev/disk/by-partuuid` so that ZFS will identify the right
> partitions even if disk naming should change at some point. Using traditional
> device nodes like `/dev/sda3` may cause intermittent import failures.
Next, export and re-import the pool with a temporary, alternate root path:
```
# zpool export zroot
# zpool import -N -R /mnt zroot
```
### Create initial filesystems
The filesystem layout on your ZFS pool is flexible. However, it is customary to
put operating system root filesystems ("boot environments") under a `ROOT`
parent:
```
# zfs create -o mountpoint=none zroot/ROOT
# zfs create -o mountpoint=/ -o canmount=noauto zroot/ROOT/void
```
Setting `canmount=noauto` on filesystems with `mountpoint=/` is useful because
it permits the creation of multiple boot environments (which may be clones of a
common Void installation or contain completely separate distributions) without
fear that ZFS auto-mounting will attempt to mount one over another.
To separate user data from the operating system, create a filesystem to store
home directories:
```
# zfs create -o mountpoint=/home zroot/home
```
Other filesystems may be created as desired.
### Mount the ZFS hierarchy
All ZFS filesystems should be mounted under the `/mnt` alternate root
established by the earlier re-import. Mount the manual-only root filesystem
before allowing ZFS to automatically mount everything else:
```
# zfs mount zroot/ROOT/void
# zfs mount -a
```
At this point, the entire ZFS hierarchy should be mounted and ready for
installation. To improve boot-time import speed, it is useful to record the
current pool configuration in a cache file that EvolutionOS will use to avoid walking
the entire device hierarchy to identify importable pools:
```
# mkdir -p /mnt/etc/zfs
# zpool set cachefile=/mnt/etc/zfs/zpool.cache zroot
```
Mount non-ZFS filesystems at the appropriate places. For example, if `/dev/sda2`
holds an ext4 filesystem that should be mounted at `/boot` and `/dev/sda1` is
the EFI system partition:
```
# mkdir -p /mnt/boot
# mount /dev/sda2 /mnt/boot
# mkdir -p /mnt/boot/efi
# mount /dev/sda1 /mnnt/boot/efi
```
### Installation
At this point, ordinary installation can proceed from the ["Base Installation"
section](https://docs.voidlinux.org/installation/guides/chroot.html#base-installation).
of the standard chroot installation guide. However, before following the
["Finalization"
instructions](./chroot.html#finalization),
make sure that the `zfs` package has been installed and `dracut` is configured
to identify a ZFS root filesystem:
```
[xchroot /mnt] # mkdir -p /etc/dracut.conf.d
[xchroot /mnt] # cat > /etc/dracut.conf.d/zol.conf <<EOF
nofsck="yes"
add_dracutmodules+=" zfs "
omit_dracutmodules+=" btrfs resume "
EOF
[xchroot /mnt] # xbps-install zfs
```
Finally, follow the "Finalization" instructions and reboot into your new system.

34
src/installation/index.md Normal file
View File

@ -0,0 +1,34 @@
# Installation
This section includes general information about the process of installing EvolutionOS.
For specific guides, see the "[Advanced Installation](./guides/index.md)"
section.
## Base system requirements
EvolutionOS can be installed on very minimalist hardware, though we recommend the
following minimums for most installations:
| Architecture | CPU | RAM | Storage |
|--------------|------------------|------|---------|
| x86_64-glibc | x86_64 | 96MB | 700MB |
| x86_64-musl | x86_64 | 96MB | 600MB |
| i686-glibc | Pentium 4 (SSE2) | 96MB | 700MB |
Note that xfce image installations require more resources.
EvolutionOS is not available for the i386, i486, or i586 architectures.
Before installing musl EvolutionOS, please read [the "musl" section](./musl.md) of this
Handbook, so that you are aware of software incompatibilities.
It is highly recommended to have a network connection available during install
to download updates, but this is not required. ISO images contain installation
data on-disk and can be installed without network connectivity.
## Downloading installation media
The most recent live images can be downloaded from
<https://hectabit.org/evolutionos/download>. Previous releases
can be found under <https://hectabit.org/assets/archive/evolutionos/>, organized by
date.

140
src/installation/live-images/guide.md Normal file
View File

@ -0,0 +1,140 @@
# Installation Guide
Once you have [downloaded](../index.md#downloading-installation-media) a EvolutionOS
image to install and [prepared](./prep.md) your install media, you are ready to
install EvolutionOS Linux.
Before you begin installation, you should determine whether your machine boots
using BIOS or UEFI. This will affect how you plan partitions. See [Partitioning
Notes](./partitions.md) for more detail.
The following features are not supported by the installer script:
- [LVM](https://en.wikipedia.org/wiki/Logical_volume_management)
- [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)
- [ZFS](https://en.wikipedia.org/wiki/ZFS)
## Booting
Boot your machine from the install media you created. If you have enough RAM,
there is an option on the boot screen to load the entire image into ram, which
will take some time but speed up the rest of the install process.
Once the live image has booted, it will autologin and run
```
# evolution-installer
```
The following sections will detail each screen of the installer.
## Keyboard
Select the keymap for your keyboard; standard "qwerty" keyboards will generally
use the "us" keymap.
## Network
Select your primary network interface. If you do not choose to use DHCP, you
will be prompted to provide an IP address, gateway, and DNS servers.
If you choose a wireless network interface, you will be prompted to provide the
SSID, encryption type (`wpa` or `wep`), and password. If `evolution-installer` fails
to connect to your network, you may need to exit the installer and configure it
manually using [wpa_supplicant](../../config/network/wpa_supplicant.md) and
[dhcpcd](../../config/network/index.md#dhcpcd) before continuing.
## Source
To install packages provided on the install image, select `Local`. Otherwise,
you may select `Network` to download the latest packages from the EvolutionOS
repository.
> **Warning:** If you are installing the desktop environment from the xfce
> image, you MUST choose `Local` for the source!
## Hostname
Select a hostname for your computer (that is all lowercase, with no spaces.)
## Locale
Select your default locale settings. This option is for glibc only, as musl does
not currently support locales.
## Timezone
Select your timezone based on standard timezone options.
## Root password
Enter and confirm your `root` password for the new installation. The password
will not be shown on screen.
## User account
Choose a login (default `evolution`) and a descriptive name for that login. Then
enter and confirm the password for the new user. You will then be prompted to
verify the groups for this new user. They are added to the `wheel` group by
default and will have `sudo` access. Default groups and their descriptions are
listed [here](../../config/users-and-groups.html#default-groups).
Login names have some restrictions, as described in
[useradd(8)](https://man.voidlinux.org/useradd.8#CAVEATS).
## Bootloader
Select the disk to install a bootloader on when EvolutionOS is installed. You may
select `none` to skip this step and install a bootloader manually after
completing the installation process. If installing a bootloader, you will also
be asked whether or not you want a graphical terminal for the GRUB menu.
## Partition
Next, you will need to partition your disks. EvolutionOS not provide a preset
partition scheme, so you will need to create your partitions manually with
[cfdisk(8)](https://man.voidlinux.org/cfdisk.8). You will be prompted with a
list of disks. Select the disk you want to partition and the installer will
launch `cfdisk` for that disk. Remember you must write the partition table to
the drive before you exit the partition editor.
If using UEFI, it is recommended you select GPT for the partition table and
create a partition (typically between 200MB-1GB) of type `EFI System`, which
will be mounted at `/boot/efi`.
If using BIOS, it is recommended you select MBR for the partition table.
Advanced users may use GPT but will need to [create a special BIOS
partition](./partitions.md#bios-system-notes) for GRUB to boot.
See the [Partitioning Notes](./partitions.md) for more details about
partitioning your disk.
## Filesystems
Create the filesystems for each partition you have created. For each partition
you will be prompted to choose a filesystem type, whether you want to create a
new filesystem on the partition, and a mount point, if applicable. When you are
finished, select `Done` to return to the main menu.
If using UEFI, create a `vfat` filesystem and mount it at `/boot/efi`.
## Review settings
It is a good idea to review your settings before proceeding. Use the right arrow
key to select the settings button and hit `<enter>`. All your selections will be
shown for review.
## Install
Selecting `Install` from the menu will start the installer. The installer will
create all the filesystems selected, and install the base system packages. It
will then generate an initramfs and install a GRUB2 bootloader to the bootable
partition.
These steps will all run automatically, and after the installation is completed
successfully, you can reboot into your new EvolutionOS install!
## Post installation
After booting into your EvolutionOS installation for the first time, [perform a system
update](../../xbps/index.md#updating).

80
src/installation/live-images/index.md Normal file
View File

@ -0,0 +1,80 @@
# Live Installers
EvolutionOS provides live installer images containing a base set of utilities, an
installer program, and package files to install a new EvolutionOS system. These live
images are also useful for repairing a system that is not able to boot or
function properly.
There are `x86_64` images for both `glibc` and `musl` based systems. There are
also images for `i686`, but only `glibc` is supported for this architecture.
Live installers are not provided for other architectures. Users of other
architectures will need to use rootfs tarballs, or perform an installation
manually.
## Installer images
EvolutionOS releases two types of images: base images and xfce images. Linux beginners
are encouraged to try one of the more full-featured xfce images, but more
advanced users may often prefer to start from a base image to install only the
packages they need.
### Base images
The base images provide only a minimal set of packages to install a usable EvolutionOS
system. These base packages are only those needed to configure a new machine,
update the system, and install additional packages from repositories.
### Xfce image
The xfce image includes a full desktop environment, web browser, and basic
applications configured for that environment. The only difference from the base
images is the additional packages and services installed.
The following software is included:
- **Window manager:** xfwm4
- **File manager:** Thunar
- **Web Browser:** Firefox
- **Terminal:** xfce4-terminal
- **Plain text editor:** Mousepad
- **Image viewer:** Ristretto
- **Other:** Bulk rename, Orage Globaltime, Orage Calendar, Task Manager, Parole
Media Player, Audio Mixer, MIME type editor, Application finder
The install process for the xfce image is the same as the base images, except
that you **must** select the `Local` source when installing. If you select
`Network` instead, the installer will download and install the latest version of
the base system, without any additional packages included on the live image.
## Accessibility support
All EvolutionOS images support the console screenreader
[espeakup](https://man.voidlinux.org/espeakup.8) and the console braille display
driver [brltty](https://man.voidlinux.org/brltty.1). These services can be
enabled at boot by pressing `s` in the bootloader menu to enable accessibility
support. On UEFI-based systems, GRUB is the bootloader, and it will play a
two-tone chime when the menu is available. On BIOS-based systems and UEFI
systems in legacy/compatibility mode, SYSLINUX is the bootloader, and no chime
is played. SYSLINUX also requires pressing the enter key after pressing `s`. The
hotkey `r` will also boot with accessibility support, but will load the live ISO
into RAM.
After booting into the installer image with accessibility support enabled, if
there are multiple soundcards detected, a short audio menu allows for the
selection of the soundcard for the screenreader. Press enter when the beep for
the desired soundcard is heard to select it.
If the `Local` installation source is selected in the installer, `espeakup` and
`brltty` will also be installed and enabled on the installed system if enabled
in the live environment.
The xfce image also supports the graphical screenreader
[orca](https://man.voidlinux.org/orca.1). This can be enabled by pressing `Win +
R` and entering `orca -r`. Orca will also be available on the installed system
if the `Local` installation source is selected.
## Kernel Command-line Parameters
EvolutionOS installer images support several kernel command-line arguments that can
change the behavior of the live system. See [the evolution-installer README for a full
list](https://github.com/evolution-linux/evolution-installer#kernel-command-line-parameters).

66
src/installation/live-images/partitions.md Normal file
View File

@ -0,0 +1,66 @@
# Partitioning Notes
Partitioning for a modern Linux distribution is generally very simple, however
the introduction of GPT and UEFI booting does bring new complexity to the
process. When creating your new partition table you will need a partition for
the root filesystem, along with a swap partition and possibly another partition
or two to facilitate booting, if required.
Note that if the disk has already been initialized, the top of the `cfdisk`
screen will show the partition layout already present: `Label: dos` for the MBR
scheme, `Label: gpt` for the GPT scheme. If you just want to erase the partition
table before starting the installer, use `wipefs(8)`. Otherwise, you can run
`cfdisk(8)` manually with the `-z` option to start with an uninitialized disk
layout; `cfdisk` will prompt you for the label type before continuing to the
main screen.
The following sections will detail the options for partition configuration.
## BIOS system notes
It is recommended that you create an MBR partition table if you are using a BIOS
boot system. This will limit the number of partitions you create to four.
It is possible to use a GPT partition table on a BIOS system, but GRUB will
require a special partition to boot properly. This partition should be at the
beginning of your disk and have a size of 1MB, with type `BIOS boot` (GUID
`21686148-6449-6E6F-744E-656564454649`). Don't create any filesystem in it. GRUB
should then install itself successfully.
## UEFI system notes
UEFI users are recommended to create a GPT partition table. UEFI booting with
GRUB also requires a special partition of the type `EFI System` with a `vfat`
filesystem mounted at `/boot/efi`. A reasonable size for this partition could be
between 200MB and 1GB. With this partition setup during the live image
installation, the installer should successfully set up the bootloader
automatically.
## Swap partitions
A swap partition is not strictly required, but recommended for systems with low
RAM. If you want to use hibernation, you will need a swap partition. The
following table has recommendations for swap partition size.
| System RAM | Recommended swap space | Swap space if using hibernation |
|------------|------------------------|---------------------------------|
| < 2GB | 2x the amount of RAM | 3x the amount of RAM |
| 2-8GB | Equal to amount of RAM | 2x the amount of RAM |
| 8-64GB | At least 4GB | 1.5x the amount of RAM |
| 64GB | At least 4GB | Hibernation not recommended |
## Boot partition (optional)
On most modern systems, a separate `/boot` partition is no longer necessary to
boot properly. If you choose to use one, note that EvolutionOS does not remove old
kernels after updates by default and also that the kernel tends to increase in
size with each new version, so plan accordingly (e.g. `/boot` with one Linux 5.x
`x86_64` kernel and GRUB occupies about 60MB).
## Other partitions
It is fine to install your system with only a large root partition, but you may
create other partitions if you want. One helpful addition could be a separate
partition for your `/home` directory. This way if you need to reinstall EvolutionOS (or
another distribution) you can save the data and configuration files in your home
directory for your new system.

76
src/installation/live-images/prep.md Normal file
View File

@ -0,0 +1,76 @@
# Prepare Installation Media
After [downloading a live image](../index.md#downloading-installation-media), it
must be written to bootable media, such as a USB drive, SD card, or CD/DVD.
## Create a bootable USB drive or SD card on Linux
### Identify the Device
Before writing the image, identify the device you'll write it to. You can do
this using [fdisk(8)](https://man.voidlinux.org/man8/fdisk.8). After connecting
the storage device, identify the device path by running:
```
# fdisk -l
Disk /dev/sda: 7.5 GiB, 8036286464 bytes, 15695872 sectors
Disk model: Your USB Device's Model
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
```
In the example above, the output shows the USB device as `/dev/sda`. On Linux,
the path to the device will typically be in the form of `/dev/sdX` (where X is a
letter) for USB devices, `/dev/mmcblkX` for SD cards, or other variations
depending on the device. You can use the model and size (`7.5GiB` above, after
the path) to identify the device if you're not sure what path it will have.
Once you've identified the device you'll use, ensure it's **not** mounted by
unmounting it with [umount(8)](https://man.voidlinux.org/man8/umount.8):
```
# umount /dev/sdX
umount: /dev/sdX: not mounted.
```
### Write the live image
The [dd(1)](https://man.voidlinux.org/man1/dd.1) command can be used to copy a
live image to a storage device. Using `dd`, write the live image to the device:
**Warning**: this will destroy any data currently on the referenced device.
Exercise caution.
```
# dd bs=4M if=/path/to/x86_64.iso of=/dev/sdX
90+0 records in
90+0 records out
377487360 bytes (377 MB, 360 MiB) copied, 0.461442 s, 818 MB/s
```
`dd` won't print anything until it's completed (or if it failed), so, depending
on the device, this can take a few minutes or longer. You can enable printing by
adding `status=progress` to the command if using GNU coreutils `dd`.
Finally, ensure all data is flushed before disconnecting the device:
```
$ sync
```
The number of records, amount copied, and rates will all vary depending on the
device and the live image you chose.
## Burning to a CD or DVD
Any disk burning application should be capable of writing the `.iso` file to a
CD or DVD. The following free software applications are available
(cross-platform support may vary):
- [Brasero](https://wiki.gnome.org/Apps/Brasero/)
- [K3B](https://userbase.kde.org/K3b)
- [Xfburn](https://docs.xfce.org/apps/xfburn/start)
It should be noted that, with a CD or DVD, live sessions will be less responsive
than with a USB stick or hard drive.

33
src/installation/musl.md Normal file
View File

@ -0,0 +1,33 @@
# musl
[musl](https://musl.libc.org/) is a libc implementation which strives to be
lightweight, fast, simple, and correct.
EvolutionOS supports musl by using it in its codebase for all target
platforms (although binary packages are not available for i686). Additionally,
all compatible packages in our official repositories are available with
musl-linked binaries in addition to their glibc counterparts.
Currently, there are nonfree and debug sub-repositories for musl, but no
multilib sub-repo.
## Incompatible software
musl practices very strict and minimal standard compliance. Many commonly used
platform-specific extensions are not present. Because of this, it is common for
software to need modification to compile and/or function properly. EvolutionOS
developers work to patch such software and hopefully get portability/correctness
changes accepted into the upstream projects.
Proprietary software usually supports only glibc systems, though sometimes such
applications are available as
[flatpaks](../config/external-applications.md#flatpak) and can be run on a musl
system. In particular, the [proprietary NVIDIA
drivers](../config/graphical-session/graphics-drivers/nvidia.md#nvidia-proprietary-driver)
do not support musl, which should be taken into account when evaluating hardware
compatibility.
### glibc chroot
Software requiring glibc can be run in a glibc
[chroot](../config/containers-and-vms/chroot.md).

104
src/theme/book.js Normal file
View File

@ -0,0 +1,104 @@
"use strict";
// Fix back button cache problem
window.onunload = function () { };
(function sidebar() {
var html = document.querySelector("html");
var sidebar = document.getElementById("sidebar");
var sidebarLinks = document.querySelectorAll('#sidebar a');
var sidebarToggleButton = document.getElementById("sidebar-toggle");
var firstContact = null;
function showSidebar() {
html.classList.remove('sidebar-hidden')
html.classList.add('sidebar-visible');
Array.from(sidebarLinks).forEach(function (link) {
link.setAttribute('tabIndex', 0);
});
sidebarToggleButton.setAttribute('aria-expanded', true);
sidebar.setAttribute('aria-hidden', false);
try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
}
function hideSidebar() {
html.classList.remove('sidebar-visible')
html.classList.add('sidebar-hidden');
Array.from(sidebarLinks).forEach(function (link) {
link.setAttribute('tabIndex', -1);
});
sidebarToggleButton.setAttribute('aria-expanded', false);
sidebar.setAttribute('aria-hidden', true);
try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
}
// Toggle sidebar
sidebarToggleButton.addEventListener('click', function sidebarToggle() {
if (html.classList.contains("sidebar-hidden")) {
showSidebar();
} else if (html.classList.contains("sidebar-visible")) {
hideSidebar();
} else {
if (getComputedStyle(sidebar)['transform'] === 'none') {
hideSidebar();
} else {
showSidebar();
}
}
});
document.addEventListener('touchstart', function (e) {
firstContact = {
x: e.touches[0].clientX,
time: Date.now()
};
}, { passive: true });
document.addEventListener('touchmove', function (e) {
if (!firstContact)
return;
var curX = e.touches[0].clientX;
var xDiff = curX - firstContact.x,
tDiff = Date.now() - firstContact.time;
if (tDiff < 250 && Math.abs(xDiff) >= 150) {
if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
showSidebar();
else if (xDiff < 0 && curX < 300)
hideSidebar();
firstContact = null;
}
}, { passive: true });
// Scroll sidebar to current active section
var activeSection = sidebar.querySelector(".active");
if (activeSection) {
sidebar.scrollTop = activeSection.offsetTop;
}
})();
(function chapterNavigation() {
document.addEventListener('keydown', function (e) {
if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
if (window.search && window.search.hasFocus()) { return; }
switch (e.key) {
case 'ArrowRight':
e.preventDefault();
var nextButton = document.querySelector('.nav-chapters.next');
if (nextButton) {
window.location.href = nextButton.href;
}
break;
case 'ArrowLeft':
e.preventDefault();
var previousButton = document.querySelector('.nav-chapters.previous');
if (previousButton) {
window.location.href = previousButton.href;
}
break;
}
});
})();

477
src/theme/css/general.css Normal file
View File

@ -0,0 +1,477 @@
body {
font-family: Arial, sans-serif;
text-align: center;
padding: 20px;
background-color: #e6e6e6;
min-width: 700px;
}
h1, h2, h3, h4, h5, h6 {
color: #333;
}
a {
color: #008040;
text-decoration: none;
text-decoration: underline;
}
a:hover {
color: #008040;
}
code {
background: #fdf6e3;
padding: 2px 4px;
border-radius: 4px;
white-space: pre-wrap;
overflow-wrap: break-word;
}
pre code {
padding: 0;
border-radius: 0;
}
pre {
padding: .5em;
margin: 1em 0;
background: #fdf6e3;
border: 1px solid #ccc;
border-radius: 4px;
}
blockquote {
margin: 20px 0;
padding: 0 20px;
padding-left: 1em;
background: #ebf4ef;
border: 1px solid #d1e6da;
border-left: none;
border-right: none;
}
li.js-unavailable {
background-color: #f6cf68;
border-radius: 10px;
margin-left: 1em;
padding-left: 1em;
padding-right: 1em;
}
table {
border-collapse: collapse;
display: block;
overflow-y: auto;
}
table td {
padding: 3px 20px;
border: 1px #fafafa solid;
}
table thead {
background: #fafafa;
}
table thead td {
font-weight: 700;
border: none;
}
table thead tr {
}
/* Alternate background colors for rows */
table tbody tr:nth-child(2n) {
background: #fafafa;
}
svg {
position: relative;
top: .125em;
width: 1em;
height: auto;
}
.hidden {
display: none;
}
.icon-button {
min-height: 60px;
max-height: 60px;
border: none;
background: none;
cursor: pointer;
padding: 1em;
}
/* void navigation */
#void-nav {
width: 100%;
min-height: 60px;
max-height: 60px;
background-color: #41e38e;
padding: 5px;
display: flex;
align-items: center;
position: fixed;
top: 0;
left: 0;
right: 0;
min-width: 700px;
overflow-y: hide;
overflow-x: auto;
white-space: nowrap;
}
#void-nav button,
#void-nav label {
fill: #e6e6e6;
height: 50px;
display: block;
line-height: 50px;
padding: 0 15px;
font-size: 1.2em;
transition: background-color 0.3s ease;
}
#void-nav ul {
list-style: none;
margin: 0;
padding: 0;
}
#void-nav ul#nav-right {
margin-left: auto;
}
#void-nav ul li {
display: inline-block;
}
#void-nav ul li a {
color: #fff;
display: block;
padding: 0 15px;
line-height: 50px;
font-size: 1.2em;
text-decoration: none;
}
#void-nav ul li ao {
background-color: #41e38e;
color: #fff;
padding: 18px 10px;
font-size: 20px;
border: none;
cursor: pointer;
text-decoration: none;
transition: background-color 0.3s ease;
min-height: 60px;
max-height: 60px;
}
#void-nav ul li ab {
background-color: #41e38e;
color: #fff;
padding: 7px 0px;
font-size: 20px;
border: none;
cursor: pointer;
text-decoration: none;
transition: background-color 0.3s ease;
min-height: 46px;
display: block;
}
#void-nav ul li ab:hover {
background-color: #008040;
}
#void-nav ul li a:hover,
#void-nav ul li a:focus,
#void-nav button:hover,
#void-nav button:focus,
#void-nav label:hover,
#void-nav label:focus {
background-color: #008040;
}
#void-nav ul li ao:hover {
min-height: 60px;
max-height: 60px;
background-color: #008040;
}
#skip-to-content {
position: absolute;
left: -999px;
top: -999px;
}
#skip-to-content:active,
#skip-to-content:focus {
position: relative;
left: 0;
top: 0;
}
/* sidebar */
.sidebar-hidden #sidebar {
background: #008040;
display: none;
}
#sidebar {
border-top: 40px solid transparent;
padding: .5em;
background: #008040;
font-size: 0.875em;
}
#sidebar ol {
list-style: none;
margin: 0;
}
#sidebar ol.chapter {
padding: 0;
line-height: 2.2em;
}
#sidebar ol.section {
padding-left: 20px;
line-height: 1.9em;
}
#sidebar a {
color: #e6e6e6;
display: block;
}
#sidebar a:hover {
color: #c8c8c8;
text-decoration: none;
}
#sidebar a.active {
color: #e6e6e6;
}
#sidebar-toggle {
display: none;
}
/* search */
#searchbar {
width: 100%;
padding: 10px 16px;
margin: 5px 0;
border-radius: 3px;
border: 1px solid #aaa;
}
#searchresults-header {
font-weight: bold;
font-size: 1em;
padding: 18px 0 0 5px;
}
ul#searchresults {
list-style: none;
padding-left: 20px;
}
ul#searchresults li {
margin: 10px 0px;
padding: 2px;
border-radius: 2px;
}
ul#searchresults span.teaser {
display: block;
clear: both;
margin: 5px 0 0 20px;
font-size: 0.8em;
}
/* chapter navigation */
#nav-wide-wrapper {
background-color: #41e38e;
max-width: 800px;
margin: 0 auto;
margin-top: 50px;
}
.previous {
float: left;
}
.next {
float: right;
right: 15px;
}
.nav-chapters {
fill: #ccc;
text-align: center;
text-decoration: none;
display: block;
max-width: 150px;
min-width: 90px;
}
.nav-chapters:hover {
text-decoration: none;
fill: #333;
}
.nav-chapters svg {
margin: 0 auto;
width: 1.5em;
}
/* layout */
body {
box-sizing: border-box;
}
#content {
display: flex;
flex-direction: row;
width: 100%;
}
#page-wrapper {
border-top: 40px solid transparent;
--content-padding: 10px;
padding: 0 var(--content-padding);
width: calc(100% - var(--content-padding) * 2);
}
#search-wrapper {
border-top: 40px solid transparent;
width: 100%;
max-width: 800px;
margin: 0 auto;
}
#page-wrapper main {
width: 100%;
max-width: 800px;
margin: 0 auto;
}
#sidebar {
max-width: 300px;
flex-shrink: 0;
}
/* 300px + 800px + 2*90px + 15px */
@media only screen and (min-width: 1295px) {
.sidebar-visible #nav-wide-wrapper {
background-color: #41e38e;
max-width: none;
margin: 0;
}
.sidebar-visible .nav-chapters {
background: none;
position: fixed;
top: 50px;
bottom: 0;
margin: 0;
justify-content: center;
align-content: center;
display: flex;
flex-direction: column;
}
}
/* 800px + 2*90px + 15px */
@media only screen and (min-width: 995px) {
.sidebar-hidden #nav-wide-wrapper {
background-color: #41e38e;
max-width: none;
margin: 0;
}
.sidebar-hidden .nav-chapters {
background: none;
position: fixed;
top: 50px;
bottom: 0;
margin: 0;
justify-content: center;
align-content: center;
display: flex;
flex-direction: column;
}
}
/* Dark Mode Styles */
body.dark-mode {
background-color: #222;
color: #fff;
}
body.dark-mode h1,
body.dark-mode h2,
body.dark-mode h3,
body.dark-mode h4,
body.dark-mode h5,
body.dark-mode h6 {
color: #fff;
}
body.dark-mode code {
background-color: #5c5c5c;
}
body.dark-mode pre {
background: #5c5c5c;
}
#void-nav.dark-mode label {
color: #6c6c6c;
}
.dark-mode table tbody tr:nth-child(2n) {
background: #5c5c5c;
}
ao.dark-mode-button {
min-height: 60px;
max-height: 60px;
background-color: #41e38e;
color: #fff;
padding: 18px 20px;
font-size: 20px;
border: none;
cursor: pointer;
text-decoration: none;
transition: background-color 0.3s ease;
}
ao.dark-mode-button:hover {
background-color: #008040;
}
img {
max-height: 40px;
margin-right: 10px;
margin-left: 10px;
}
.container {
display: flex;
justify-content: flex-end;
}

54
src/theme/css/print.css Normal file
View File

@ -0,0 +1,54 @@
#sidebar,
#menu-bar,
.nav-chapters,
.mobile-nav-chapters {
display: none;
}
#page-wrapper.page-wrapper {
transform: none;
margin-left: 0px;
overflow-y: initial;
}
#content {
max-width: none;
margin: 0;
padding: 0;
}
.page {
overflow-y: initial;
}
code {
background-color: #666666;
border-radius: 5px;
/* Force background to be printed in Chrome */
-webkit-print-color-adjust: exact;
}
pre > .buttons {
z-index: 2;
}
a, a:visited, a:active, a:hover {
color: #4183c4;
text-decoration: none;
}
h1, h2, h3, h4, h5, h6 {
page-break-inside: avoid;
page-break-after: avoid;
}
pre, code {
page-break-inside: avoid;
white-space: pre-wrap;
}
svg {
display: none !important;
}

BIN
src/theme/favicon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

251
src/theme/index.hbs Normal file
View File

@ -0,0 +1,251 @@
<!DOCTYPE HTML>
<html lang="{{ language }}" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="utf-8">
<title>EvolutionOS Wiki</title>
<meta content="EvolutionOS Wiki" property="og:title">
<meta content="This is the wiki for EvolutionOS, the Linux Distro that redefines speed." property="og:title">
<meta content="EvolutionOS Wiki" property="og:site_name">
<meta content="https://ada.ctaposter.xyz/assets/img/evolutionlogo.svg" property="og:image">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="{{ path_to_root }}{{ favicon_png }}">
<link rel="stylesheet" href="{{ path_to_root }}css/general.css">
<link rel="stylesheet" href="{{ path_to_root }}css/print.css" media="print">
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "{{ path_to_root }}";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var sidebar = localStorage.getItem('mdbook-sidebar');
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<header>
<nav id="void-nav">
<ul>
<li><a id="skip-to-content" tabindex="1" href="#main">Skip to content</a></li>
</ul>
<ul id="nav-left">
<li>
<ab href="/">
<img src="/assets/img/evolutionlogo.svg" alt="EvolutionOS Logo">
</ab>
</li>
</ul>
<ul>
<li><ao href="/evolutionos/download">Download</ao></li>
<li><ao href="/evolutionos/wiki">Wiki</ao></li>
<li><ao href="https://centrifuge.hectabit.org/evolutionos/evolution-packages">Source Code</ao></li>
<li><ao href="https://discord.gg/yh5HaqN6CD">Discord</ao></li>
<li><ao href="/evolutionos/donate">Donate</ao></li>
<ao onclick="toggleDarkMode()" class="dark-mode-button">Toggle Dark Mode</ao>
<li>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">
<path d="M7.5 13c3.04 0 5.5-2.46 5.5-5.5S10.54 2 7.5 2 2 4.46 2 7.5 4.46 13 7.5 13zm4.55.46C10.79 14.43 9.21 15 7.5 15 3.36 15 0 11.64 0 7.5S3.36 0 7.5 0C11.64 0 15 3.36 15 7.5c0 1.71-.57 3.29-1.54 4.55l6.49 6.49-1.41 1.41-6.49-6.49z"></path>
</svg>
</button>
</li>
<noscript>
<li class="js-unavailable">Search functionality requires JavaScript</li>
</noscript>
<li>
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar" aria-expanded="false">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">
<path d="M1 3v2h18V3zm0 8h18V9H1zm0 6h18v-2H1z"></path>
</svg>
</button>
</li></ul>
</nav>
</header>
<div id="content">
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" aria-label="Table of contents">
{{#toc}}{{/toc}}
</nav>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="page-wrapper">
{{#if search_enabled}}
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
{{/if}}
<main id="main">
{{{ content }}}
</main>
<nav id="nav-wide-wrapper" aria-label="Page navigation">
{{#previous}}
<a href="{{ path_to_root }}{{link}}" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
<path d="M4 10l9 9 1.4-1.5L7 10l7.4-7.5L13 1z"/>
</svg>
</a>
{{/previous}}
{{#next}}
<a href="{{ path_to_root }}{{link}}" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
<path d="M7 1L5.6 2.5 13 10l-7.4 7.5L7 19l9-9z"/>
</svg>
</a>
{{/next}}
</nav>
</div>
</div>
{{#if livereload}}
<!-- Livereload script (if served using the cli tool) -->
<script type="text/javascript">
var socket = new WebSocket("{{{livereload}}}");
socket.onmessage = function (event) {
if (event.data === "reload") {
socket.close();
location.reload(true); // force reload from server (not from cache)
}
};
window.onbeforeunload = function() {
socket.close();
}
</script>
{{/if}}
{{#if search_js}}
<script src="{{ path_to_root }}elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="{{ path_to_root }}mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="{{ path_to_root }}searcher.js" type="text/javascript" charset="utf-8"></script>
{{/if}}
<script src="{{ path_to_root }}book.js" type="text/javascript" charset="utf-8"></script>
<script>
// Check if a dark mode cookie exists, and apply dark mode if it does
if (getCookie("darkMode") === "true") {
applyDarkMode();
}
// Detect dark mode
function isDarkModeEnabled() {
return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
}
if (isDarkModeEnabled()) {
applyDarkMode();
} else {
console.log('Dark mode is not enabled.');
}
function toggleDarkMode() {
if (getCookie("darkMode") === "true") {
// Disable dark mode
setCookie("darkMode", "false", 365);
applyLightMode();
} else {
// Enable dark mode
setCookie("darkMode", "true", 365);
applyDarkMode();
}
}
function applyDarkMode() {
document.body.classList.add("dark-mode");
}
function applyLightMode() {
document.body.classList.remove("dark-mode");
}
// Helper functions for handling cookies
function setCookie(name, value, days) {
var expires = "";
if (days) {
var date = new Date();
date.setTime(date.getTime() + (days * 24 * 60 * 60 * 1000));
expires = "; expires=" + date.toUTCString();
}
document.cookie = name + "=" + (value || "") + expires + "; path=/";
}
function getCookie(name) {
var nameEQ = name + "=";
var ca = document.cookie.split(';');
for (var i = 0; i < ca.length; i++) {
var c = ca[i];
while (c.charAt(0) === ' ') c = c.substring(1, c.length);
if (c.indexOf(nameEQ) === 0) return c.substring(nameEQ.length, c.length);
}
return null;
}
</script>
<script>
const aoLinks = document.querySelectorAll('ao[href]');
aoLinks.forEach(link => {
link.addEventListener('click', function(event) {
event.preventDefault(); // Prevent default link behavior
const href = link.getAttribute('href');
if (href) {
window.location.href = href; // Navigate to the specified URL
}
});
});
</script>
<script>
const abLinks = document.querySelectorAll('ab[href]');
abLinks.forEach(link => {
link.addEventListener('click', function(event) {
event.preventDefault(); // Prevent default link behavior
const href = link.getAttribute('href');
if (href) {
window.location.href = href; // Navigate to the specified URL
}
});
});
</script>
</body>
</html>

103
src/xbps/advanced-usage.md Normal file
View File

@ -0,0 +1,103 @@
# Advanced Usage
## Downgrading
XBPS allows you to downgrade a package to a specific package version.
### Via xdowngrade
The easiest way to downgrade is to use `xdowngrade` from the `xtools` package,
specifying the package version to which you wish to downgrade:
```
# xdowngrade /var/cache/xbps/pkg-1.0_1.xbps
```
### Via XBPS
XBPS can be used to downgrade to a package version that is no longer available
in the repository index.
If the package version had been installed previously, it will be available in
`/var/cache/xbps/`. If not, it will need to be obtained from elsewhere; for the
purposes of this example, it will be assumed that the package version has been
added to `/var/cache/xbps/`.
First add the package version to your local repository:
```
# xbps-rindex -a /var/cache/xbps/pkg-1.0_1.xbps
```
Then downgrade with `xbps-install`:
```
# xbps-install -R /var/cache/xbps/ -f pkg-1.0_1
```
The `-f` flag is necessary to force downgrade/re-installation of an already
installed package.
## Holding packages
To prevent a package from being updated during a system update, use
[xbps-pkgdb(1)](https://man.voidlinux.org/xbps-pkgdb.1):
```
# xbps-pkgdb -m hold <package>
```
The hold can be removed with:
```
# xbps-pkgdb -m unhold <package>
```
## Repository-locking packages
If you've used `xbps-src` to build and install a package from a customized
template, or with custom build options, you may wish to prevent system updates
from replacing that package with a non-customized version. To ensure that a
package is only updated from the same repository used to install it, you can
*repolock* it via [xbps-pkgdb(1)](https://man.voidlinux.org/xbps-pkgdb.1):
```
# xbps-pkgdb -m repolock <package>
```
To remove the repolock:
```
# xbps-pkgdb -m repounlock <package>
```
## Ignoring Packages
Sometimes you may wish to remove a package whose functionality is being provided
by another package, but will be unable to do so due to dependency issues. For
example, you may wish to use [doas(1)](https://man.voidlinux.org/doas.1) instead
of [sudo(8)](https://man.voidlinux.org/sudo.8), but will be unable to remove the
`sudo` package due to it being a dependency of the `base-system` package. To
remove it, you will need to *ignore* the `sudo` package.
To ignore a package, add an appropriate `ignorepkg` entry in an
[xbps.d(5)](https://man.voidlinux.org/xbps.d.5) configuration file. For example:
```
ignorepkg=sudo
```
You will then be able to remove the `sudo` package using
[xbps-remove(1)](https://man.voidlinux.org/xbps-remove.1).
## Virtual Packages
Virtual packages can be created with
[xbps.d(5)](https://man.voidlinux.org/xbps.d.5) `virtualpkg` entries. Any
request to the virtual package will be resolved to the real package. For
example, to create a `linux` virtual package which will resolve to the
`linux5.6` package, create an `xbps.d` configuration file with the contents:
```
virtualpkg=linux:linux5.6
```

Some files were not shown because too many files have changed in this diff Show More