-
Notifications
You must be signed in to change notification settings - Fork 536
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Started a re-write of the docs (#1967)
* Started a re-write of the docs, using CSV for tables and re-organizing parameter definitions * Added final config options in --config, some have external references which needs to be populated * Forgot to escape a comma * Clarified a note * Added disk configuration and disk encryption docs * Changed way of installing using source and python * Added a 'list script' that lists available scripts. This could be converted to a argparse later. But this does the trick for now. And it's added to ease documentation and listing of available options. * Added a 'Known issues' section, as well as renamed the issues tab * Finished up the known issues section * Added a section regarding --plugin * Added plugin description, tweaked disk_config to the latest changes from #2221 * Added custom-commands docs, and improved some creds and known issue links
- Loading branch information
Showing
21 changed files
with
795 additions
and
471 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
import glob | ||
import pathlib | ||
|
||
print("The following are viable --script options:") | ||
|
||
for script in [pathlib.Path(x) for x in glob.glob(f"{pathlib.Path(__file__).parent}/*.py")]: | ||
if script.stem in ['__init__', 'list']: | ||
continue | ||
|
||
print(f" {script.stem}") |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
.wy-nav-content { | ||
max-width: none; | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
{% extends "!layout.html" %} | ||
{% block extrahead %} | ||
<link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css"> | ||
{% endblock %} |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
.. _archinstall.Plugins: | ||
|
||
Python Plugins | ||
============== | ||
|
||
``archinstall`` supports plugins via two methods. | ||
|
||
First method is directly via the ``--plugin`` parameter when running as a CLI tool. This will load a specific plugin locally or remotely via a path. | ||
|
||
The second method is via Python's built in `plugin discovery`_ using `entry points`_ categorized as ``archinstall.plugin``. | ||
|
||
``--plugin`` parameter | ||
---------------------- | ||
|
||
The parameter has the benefit of being stored in the ``--conf`` state, meaning when re-running an installation — the plugin will automatically be loaded. | ||
It's limitation is that it requires an initial path to be known and written and be cumbersome. | ||
|
||
Plugin Discovery | ||
---------------- | ||
|
||
This method allows for multiple plugins to be loaded with the drawback that they have to be installed beforehand on the system running ``archinstall``. | ||
This mainly targets those who build their own ISO's and package specific setups for their needs. | ||
|
||
|
||
What's supported? | ||
----------------- | ||
|
||
Currently the documentation for this is scarse. Until that is resolved, the best way to find supported features is to search the source code for `plugin.on_ <https://github.com/search?q=repo%3Aarchlinux%2Farchinstall+%22plugin.on_%22&type=code>`_ as this will give a clear indication of which calls are made to plugins. | ||
|
||
How does it work? | ||
----------------- | ||
|
||
``archinstall`` plugins use a discovery-driven approach where plugins are queried for certain functions. | ||
As an example, if a plugin has the following function: | ||
|
||
.. code-block:: python | ||
def on_pacstrap(*packages): | ||
... | ||
The function :code:`archinstall.Pacman().strap(["some packages"])` is hardcoded to iterate plugins and look for :code:`on_pacstrap` in the plugin. | ||
If the function exists, :code:`.strap()` will call the plugin's function and replace the initial package list with the result from the plugin. | ||
|
||
The best way to document these calls is currently undecided, as it's hard to document this behavior dynamically. | ||
|
||
Writing your own? | ||
----------------- | ||
|
||
The simplest way currently is to look at a reference implementation or the community. Two of these are: | ||
|
||
* `torxed/archinstall-aur <https://github.com/torxed/archinstall-aur>`_ | ||
* `phisch/archinstall-aur <https://github.com/phisch/archinstall-aur>`_ | ||
|
||
And search for `plugin.on_ <https://github.com/search?q=repo%3Aarchlinux%2Farchinstall+%22plugin.on_%22&type=code>`_ in the code base to find what ``archinstall`` will look for. PR's are welcome to widen the support for this. | ||
|
||
.. _plugin discovery: https://packaging.python.org/en/latest/specifications/entry-points/ | ||
.. _entry points: https://docs.python.org/3/library/importlib.metadata.html#entry-points |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
Key,Value(s),Description,Required | ||
additional-repositories,[ `multilib <https://wiki.archlinux.org/title/Official_repositories#multilib>`_!, `testing <https://wiki.archlinux.org/title/Official_repositories#Testing_repositories>`_ ],Enables one or more of the testing and multilib repositories before proceeding with installation,No | ||
archinstall-language,`lang <https://github.com/archlinux/archinstall/blob/master/archinstall/locales/languages.json>`__,Sets the TUI language used *(make sure to use the ``lang`` value not the ``abbr``)*,No | ||
audio_config,`pipewire <https://wiki.archlinux.org/title/PipeWire>`_!, `pulseaudio <https://wiki.archlinux.org/title/PulseAudio>`_,Audioserver to be installed,No | ||
bootloader,`Systemd-boot <https://wiki.archlinux.org/title/Systemd-boot>`_!, `grub <https://wiki.archlinux.org/title/GRUB>`_,Bootloader to be installed *(grub being mandatory on BIOS machines)*,Yes | ||
debug,``true``!, ``false``,Enables debug output,No | ||
disk_config,*Read more under* :ref:`disk config`,Contains the desired disk setup to be used during installation,No | ||
disk_encryption,*Read more about under* :ref:`disk encryption`,Parameters for disk encryption applied ontop of ``disk_config``,No | ||
hostname,``str``,A string definining your machines hostname on the network *(defaults to ``archinstall``)*,No | ||
kernels,[ `linux <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-hardened <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-lts <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-rt <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-rt-lts <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_!, `linux-zen <https://wiki.archlinux.org/title/Kernel#Officially_supported_kernels>`_ ],Defines which kernels should be installed and setup in the boot loader options,Yes | ||
custom-commands,*Read more under* :ref:`custom commands`,Custom commands that will be run post-install chrooted inside the installed system,No | ||
locale_config,{kb_layout: `lang <https://wiki.archlinux.org/title/Linux_console/Keyboard_configuration>`__!, sys_enc: `Character encoding <https://wiki.archlinux.org/title/Locale>`_!, sys_lang: `locale <https://wiki.archlinux.org/title/Locale>`_},Defines the keyboard key map!, system encoding and system locale,No | ||
mirror_config,{custom_mirrors: [ https://... ]!, mirror_regions: { "Worldwide": [ "https://geo.mirror.pkgbuild.com/$repo/os/$arch" ] } },Sets various mirrors *(defaults to ISO's ``/etc/pacman.d/mirrors`` if not defined)*,No | ||
network_config,*`see options under Network Configuration`*,Sets which type of *(if any)* network configuration should be used,No | ||
no_pkg_lookups,``true``!, ``false``,Disabled package checking against https://archlinux.org/packages/,No | ||
ntp,``true``!, ``false``,enables or disables `NTP <https://wiki.archlinux.org/title/Network_Time_Protocol_daemon>`_ during installation,No | ||
offline,``true``!, ``false``,enables or disables certain online checks such as mirror reachability etc,No | ||
packages,[ <package1>!, <package2>!, ... ],A list of packages to install during installation,No | ||
parallel downloads,0-∞,sets a given number of paralell downloads to be used by `pacman <https://wiki.archlinux.org/title/Pacman#Enabling_parallel_downloads>`_,No | ||
profile_config,*`read more under the profiles section`*,Installs a given profile if defined,No | ||
script,`guided <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py>`__! *(default)*!, `minimal <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/minimal.py>`__!, `only_hdd <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/only_hdd.py>`_!, `swiss <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/swiss.py>`_!, `unattended <https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/unattended.py>`_,When used to autorun an installation!, this sets which script to autorun with,No | ||
silent,``true``!, ``false``,disables or enables user questions using the TUI,No | ||
swap,``true``!, ``false``,enables or disables swap,No | ||
timezone,`timezone <https://wiki.archlinux.org/title/System_time#Time_zone>`_,sets a timezone for the installed system,No |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
.. _custom commands: | ||
|
||
Custom Commands | ||
=============== | ||
|
||
| Custom commands is a configuration entry that allows for executing custom commands post-installation. | ||
| The commands are executed with `arch-chroot <https://man.archlinux.org/man/extra/arch-install-scripts/arch-chroot.8.en>`_. | ||
The option takes a list of arguments, an example is: | ||
|
||
.. code-block:: json | ||
{ | ||
"custom-commands": [ | ||
"hostname new-hostname" | ||
] | ||
} | ||
| The following example will set a new hostname in the installed system. | ||
| The example is just to illustrate that the command is not run in the ISO but inside the installed system after the base system is installed. | ||
More examples can be found in the code repository under `examples/ <https://github.com/archlinux/archinstall/tree/e6344f93f7e476d05bbcd642f2ed91fdde545870/examples>`_ |
Oops, something went wrong.