ExternalVendorCode/genode
1
0
Fork 0
mirror of https://github.com/genodelabs/genode.git synced 2025-01-03 04:26:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update Sculpt documentation for version 20.08

Browse Source
This commit is contained in:
Norman Feske 2020-09-16 15:35:29 +02:00 committed by Christian Helmuth
parent d7eb174c88
commit 3e83b4b39e
1 changed files with 104 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
repos/gems/recipes/pkg/sculpt/README
View File

@ -1,7 +1,7 @@
============================= =============================
Sculpt Operating System 20.02 Sculpt Operating System 20.08
============================= =============================
@ -58,7 +58,7 @@ Your feedback is appreciated!
[https://www.genode-labs.com] [https://www.genode-labs.com]
A printable PDF version of this document is available at A printable PDF version of this document is available at
[https://genode.org/documentation/sculpt-20-02.pdf]. [https://genode.org/documentation/sculpt-20-08.pdf].
Hardware requirements and preparations Hardware requirements and preparations
@ -113,43 +113,47 @@ from [https://genode.org/download/sculpt].
Right after system boot, Sculpt's system-management user interface Right after system boot, Sculpt's system-management user interface
("Leitzentrale") appears. ("Leitzentrale") appears.
The panel at the top of the screen contains two centered tabs for switching The panel at the top of the screen contains two centered tabs for switching
between the "Components" view and a "Files" view. between the "Components" view and a "Files" view (Figure [sculpt_20_08_panel]).
The components view displays a live graph of the software components and their The components view displays a live graph of the software components and their
relationships. It also provides convenient access to the connected storage relationships. It also provides convenient access to the connected storage
devices. The "Log" button at the right side of the panel reveals diagnostic devices. The "Log" button at the right side of the panel reveals diagnostic
messages, the "Network" button allows you to configure network connectivity, messages, the "Network" button allows you to configure network connectivity,
and the "Settings" button on the left gives access to a few user-interface and the "Settings" button on the left gives access to a few user-interface
tweaks. tweaks (Figure [sculpt_20_08_panel]).
[image sculpt_20.02_panel 60%] [image sculpt_20_08_panel 60%]
Consider the following steps as a warm-up with Sculpt OS. Consider the following steps as a warm-up with Sculpt OS.
Select the in-memory file system as *default storage location* by clicking Select the in-memory file system as *default storage location* by clicking
on the "ram fs" component in the graph and pressing the "Use" button. on the "ram fs" component in the graph and pressing the "Use" button
(Figure [sculpt_20_08_use_ram_fs]).
This way, software will be installed solely into memory without accessing any This way, software will be installed solely into memory without accessing any
real storage device. real storage device.
[image sculpt_20.02_use_ram_fs 40%] [image sculpt_20_08_use_ram_fs 40%]
Enable *networking* in the "Network" dialog by selecting the "Wired" or Enable *networking* in the "Network" dialog by selecting the "Wired" or
"Wifi" option. In the latter case, select an access point and enter the "Wifi" option. In the latter case, select an access point and enter the
corresponding passphrase (if needed). A successful network connection is corresponding passphrase (if needed). A successful network connection is
indicated by the IP address displayed at the bottom of the network dialog. indicated by the IP address displayed at the bottom of the network dialog
(Figure [sculpt_20_08_network]).
[image sculpt_20.02_network 40%] [image sculpt_20_08_network 40%]
With a storage location selected and established network connectivity, it is With a storage location selected and established network connectivity, it is
time to *install and start* additional components by clicking on the '+' time to *install and start* additional components by clicking on the '+'
button of the components view. Select "Depot ..." from the menu. button of the components view. Select "Depot ..." from the menu
(Figure [sculpt_20_08_menu]).
[image sculpt_20.02_menu 40%] [image sculpt_20_08_menu 40%]
The depot contains software packages, which can be obtained by different The depot contains software packages, which can be obtained by different
independent software providers. The selection of software providers is independent software providers. The selection of software providers is
completely up to the user and can be defined in the "Selection ..." sub menu. completely up to the user and can be defined in the "Selection ..." sub menu
(Figure [sculpt_20_08_select]).
[image sculpt_20.02_select 40%] [image sculpt_20_08_select 40%]
Select "genodelabs" to download the directory of software officially Select "genodelabs" to download the directory of software officially
provided by Genode Labs. Note that the other options are not necessarily provided by Genode Labs. Note that the other options are not necessarily
@ -163,17 +167,18 @@ When now going back to the depot menu, a new menu item "genodelabs ..."
appears. It leads to a catalogue of software browsable via hierarchically appears. It leads to a catalogue of software browsable via hierarchically
structured menus. As a starter, let's add a desktop background. structured menus. As a starter, let's add a desktop background.
In the "GUI ..." sub menu, a click on the first item named "sticks blue In the "GUI ..." sub menu, a click on the first item named "sticks blue
backdrop" reveals the option to install the package. backdrop" reveals the option to install the package
(Figure [sculpt_20_08_install_backdrop]).
[image sculpt_20.02_install_backdrop 40%] [image sculpt_20_08_install_backdrop 40%]
A click on the "Install" button triggers the download of the package and its A click on the "Install" button triggers the download of the package and its
dependencies. Once the download is complete, the menu presents a configuration dependencies. Once the download is complete, the menu presents a configuration
dialog that allows you to define the interplay of the new component with the dialog that allows you to define the interplay of the new component with the
system. In this particular case, you have to decide for a GUI service to be system. In this particular case, you have to decide for a GUI service to be
used by the backdrop. used by the backdrop (Figure [sculpt_20_08_backdrop_routes]).
[image sculpt_20.02_backdrop_routes 40%] [image sculpt_20_08_backdrop_routes 40%]
The first option "system GUI server" would grant direct access to the system's The first option "system GUI server" would grant direct access to the system's
low-level GUI server, which is normally not used by applications but by low-level GUI server, which is normally not used by applications but by
@ -184,17 +189,18 @@ appears as a layer behind all other applications. The fourth option "keyboard
focus" is preserved for a single component that controls the keyboard focus. focus" is preserved for a single component that controls the keyboard focus.
In our case, "desktop background" is the correct choice. In our case, "desktop background" is the correct choice.
Once the configuration is complete, a new button for adding the component to Once the configuration is complete, a new button for adding the component to
the system appears. the system appears (Figure [sculpt_20_08_add_backdrop]).
[image sculpt_20.02_add_backdrop 40%] [image sculpt_20_08_add_backdrop 40%]
After pressing the button, you should notice a slight visual change. *Press* After pressing the button, you should notice a slight visual change. *Press*
*F12* to toggle between the Leitzentrale and the desktop. Now, the backdrop *F12* to toggle between the Leitzentrale and the desktop. Now, the backdrop
should become visible in full glory. In the component graph, the new component should become visible in full glory. In the component graph, the new component
appears connected to the "GUI". A click on the component reveals further appears connected to the "GUI". A click on the component reveals further
information along with the option to remove it from the system. information along with the options to remove it from the system or to
restart it (Figure [sculpt_20_08_backdrop_selected]).
[image sculpt_20.02_backdrop_selected 40%] [image sculpt_20_08_backdrop_selected 40%]
As a next step, let us add a window system. In the '+' menu, you can find As a next step, let us add a window system. In the '+' menu, you can find
a readily packaged window system at _genodelabs_ -> _GUI_ -> _themed wm_. a readily packaged window system at _genodelabs_ -> _GUI_ -> _themed wm_.
@ -215,11 +221,12 @@ to obtain clipboard content.
After adding the component, the "themed wm" will appear in the components view. After adding the component, the "themed wm" will appear in the components view.
To give the window system a quick try, add the small demo you can find at To give the window system a quick try, add the small demo you can find at
_genodelabs_ -> _Demos_ -> _nano3d_ and assign its _GUI_ to our "themed wm". _genodelabs_ -> _Demos_ -> _nano3d_ and assign its _GUI_ to our "themed wm".
You will be greeted with the window as shown in Figure [sculpt_ce_nano3d].
[image sculpt_ce_nano3d 40%] [image sculpt_ce_nano3d 40%]
Next, let us add a *small Unix-like subsystem* called _noux_ hosted in a Next, let us add a *small Unix-like subsystem* called _system shell_ hosted in
window. This noux runtime will be presented in a terminal window. The font a window. This subsystem will be presented in a terminal window. The font
used by the terminal is obtained from a font server. To create the font used by the terminal is obtained from a font server. To create the font
server, install and add the package _genodelabs_ -> _GUI_ -> _fonts fs_, and server, install and add the package _genodelabs_ -> _GUI_ -> _fonts fs_, and
assign the _system font configuration_ to its _ROM (config)_. "ROM" means assign the _system font configuration_ to its _ROM (config)_. "ROM" means
@ -227,8 +234,8 @@ read-only memory. So we grant the font server read-only access to the system's
default font configuration (which is generated automatically according to the default font configuration (which is generated automatically according to the
screen resolution). screen resolution).
For starting the actual noux runtime, select and install For starting the actual system shell, select and install
_genodelabs_ -> _Tools_ -> _noux-system_ from the menu. The configuration _genodelabs_ -> _Tools_ -> _system shell_ from the menu. The configuration
dialog is a bit more elaborate this time. dialog is a bit more elaborate this time.
:GUI: defines the GUI server that should host the terminal. :GUI: defines the GUI server that should host the terminal.
@ -238,7 +245,7 @@ dialog is a bit more elaborate this time.
_/config/_ inside the instance. There exist a number of options. _/config/_ inside the instance. There exist a number of options.
By selecting _writeable system configuration_, we grant control over By selecting _writeable system configuration_, we grant control over
the whole system. It goes without saying that this should not be done the whole system. It goes without saying that this should not be done
lightheartedly. However, since we trust the "noux-system" package from lightheartedly. However, since we trust the "system shell" package from
Genode Labs, let's do it. Genode Labs, let's do it.
:File system (report): defines the file system to be mounted at _/report/_ :File system (report): defines the file system to be mounted at _/report/_
@ -264,20 +271,25 @@ dialog is a bit more elaborate this time.
clipboard can be found in clipboard can be found in
[https://genodians.org/nfeske/2019-07-03-copy-paste - a dedicated article]. [https://genodians.org/nfeske/2019-07-03-copy-paste - a dedicated article].
With those decisions taken, a fresh noux runtime can be started, which appears :Region maps:
in a window. Select "custom virtual memory objects" to allow the subsystem to manage
its virtual memory layout by itself.
[image sculpt_ce_noux 60%] With those decisions taken, a fresh system shell can be started, which appears
in a window (Figure [sculpt_20_08_system_shell]).
When selecting the "noux-system" component in the graph, the [image sculpt_20_08_system_shell 60%]
When selecting the "system system" component in the graph, the
relationship to the other components of the system is presented. This provides relationship to the other components of the system is presented. This provides
a convenient way to reveal the _trusted computing base_ of the selected a convenient way to reveal the _trusted computing base_ of the selected
component. For example, since there is no connection from _noux-system_ to the component (Figure [sculpt_20_08_system_shell_selected]).
For example, since there is no connection from _system shell_ to the
_nic_router_ we know that this component is isolated from the network. The _nic_router_ we know that this component is isolated from the network. The
network-related components are outside the trusted computing base of the network-related components are outside the trusted computing base of the
noux instance. system shell.
[image sculpt_20.02_noux_selected 50%] [image sculpt_20_08_system_shell_selected 50%]
Further exploration Further exploration
@ -355,7 +367,7 @@ Static system
The first - static - part of the system is baked into the boot image. It The first - static - part of the system is baked into the boot image. It
contains components that must be shared by the upper - dynamic - parts and contains components that must be shared by the upper - dynamic - parts and
defines the relationships between the upper parts via a static policy that defines the relationships between the upper parts via a static policy that
is fixed by the creator of the boot image. is fixed by the creator of the boot image (Figure [sculpt_static]).
; Drivers | Leitzentrale | Runtime ; Drivers | Leitzentrale | Runtime
; -------------------------------------------------------- ; --------------------------------------------------------
@ -406,12 +418,12 @@ device resources.
; : : : : : ; : : : : :
; (platform) (event) (USB) (framebuffer) (block) ; (platform) (event) (USB) (framebuffer) (block)
[image sculpt_drivers 80%] [image sculpt_20_08_drivers 80%]
Services provided by the drivers subsystem Services provided by the drivers subsystem
As illustrated by Figure [sculpt_drivers], some drivers like the framebuffer As illustrated by Figure [sculpt_20_08_drivers], some drivers like the
driver live in a dynamically managed subsystem that depends on runtime framebuffer driver live in a dynamically managed subsystem that depends on
discovery of the hardware by the so-called driver-manager component. runtime discovery of the hardware by the so-called driver-manager component.
Whenever an Intel graphics device is present, the Intel framebuffer driver Whenever an Intel graphics device is present, the Intel framebuffer driver
is spawned. Otherwise, a generic VESA driver or a driver for a is spawned. Otherwise, a generic VESA driver or a driver for a
boot-time-initialized framebuffer is used. boot-time-initialized framebuffer is used.
@ -445,28 +457,30 @@ connectivity. Most importantly, however, it allows the user to access the
_config_ and _report_ file systems. Both file systems are readily accessible _config_ and _report_ file systems. Both file systems are readily accessible
under the "Files" tab of the panel. The file browser allows you to traverse under the "Files" tab of the panel. The file browser allows you to traverse
directory hierarchies, inspect individual files, and edit files. directory hierarchies, inspect individual files, and edit files.
Alternatively to the "Files" tab, Sculpt 20.02 features a command-line Alternatively to the "Files" tab, Sculpt 20.08 features a command-line
interface. To spawn this command-line interface, click on the "ram fs" interface. To spawn this command-line interface, click on the "ram fs"
component in the graph and select "Inspect". In the panel, a third tab named component in the graph and select "Inspect". In the panel, a third tab named
"Inspect" appears, which hosts the command-line interface. "Inspect" appears, which hosts the command-line interface
(Figure [sculpt_20_08_inspect_tab]).
[image sculpt_20.02_inspect_tab 60%] [image sculpt_20_08_inspect_tab 60%]
The inspect tab hosts a small Unix-like runtime called noux as user The inspect tab hosts a small Unix-like runtime as user interface. Don't let
interface. Don't let the presence of a Unix shell mislead you. the presence of a Unix shell mislead you. Sculpt is not a Unix system. It
Sculpt is not a Unix system. It merely uses Unix subsystems in the form of merely uses Unix-like subsystems as convenient tools for managing and editing
noux instances as convenient tools for managing and editing files. files. Within the inspect tab, you can interact with both the report and
Within the inspect tab, you can interact with both the report and config file systems using familiar commands such as the bash shell, a subset
config file systems using familiar commands such as the bash shell, a of coreutils, and Vim.
subset of coreutils, and Vim.
Besides the interactive shell, the Leitzentrale employs a noux instance that _Note that the interactive inspect view is not bullet-proof. Should you get_
gives you a quick glance at the most recent log messages. The log is also _stuck, you may re-spawn it at any time by toggling the "Inspect" button._
Besides the interactive shell, the Leitzentrale employs a simple viewer of the
most recent diagnostic log messages. You can toggle the log display via the
panel's log button. Each line of the log is prefixed by the label of the
originating component. For detailed analysis, the complete log is also
available at _report/log_ and can be browsed with Vim in the inspect window. available at _report/log_ and can be browsed with Vim in the inspect window.
_Noux is not bullet-proof. Should you get stuck, you may re-spawn it at_
_any time by toggling the "Inspect" button._
Tweaking and inspecting the system Tweaking and inspecting the system
================================== ==================================
@ -482,14 +496,15 @@ Interactive file browser
The "Files" tab of the panel switches the main screen area to a simple file The "Files" tab of the panel switches the main screen area to a simple file
browser that lists all file systems available, in particular the _config_ browser that lists all file systems available, in particular the _config_
and _report_ file systems. By toggling one of the file-system buttons, the and _report_ file systems (Figure [sculpt_20_08_files_tab]).
By toggling one of the file-system buttons, the
respective directory hierarchy can be browsed. When hovering a file, an "Edit" respective directory hierarchy can be browsed. When hovering a file, an "Edit"
or "View" button appears, which can be used to open the file in a text area or "View" button appears, which can be used to open the file in a text area
that appears on the right side of the file browser. The editor supports the that appears on the right side of the file browser. The editor supports the
usual notepad-like motions, operations, and shortcuts (control-c for copy, usual notepad-like motions, operations, and shortcuts (control-c for copy,
control-v for paste, control-s for save). control-v for paste, control-s for save).
[image sculpt_20.02_files_tab 80%] [image sculpt_20_08_files_tab 80%]
_Note that the file browser as the most recent addition to Sculpt does not_ _Note that the file browser as the most recent addition to Sculpt does not_
_yet support file operations like the copying, renaming, or removal of_ _yet support file operations like the copying, renaming, or removal of_
@ -528,7 +543,7 @@ Adjusting the user-input handling
By default, Sculpt uses the US-English keyboard layout with a functioning By default, Sculpt uses the US-English keyboard layout with a functioning
capslock key. You may possibly want to adjust the former and - as a Vim capslock key. You may possibly want to adjust the former and - as a Vim
user - most likely discharge the latter. As mentioned in Section user - most likely discharge the latter. As mentioned in Section
[Drivers subsystem], user input is processed by the event-filter component. [System overview], user input is processed by the event-filter component.
You can edit this component's configuration via You can edit this component's configuration via
! inspect:/> vim /config/event_filter ! inspect:/> vim /config/event_filter
@ -624,7 +639,7 @@ Whenever adding a new component via the '+' menu, one has to define how to
connect the component with the rest of the system. It is important to know connect the component with the rest of the system. It is important to know
what the presented options mean to take educated decisions. what the presented options mean to take educated decisions.
[image sculpt_20.02_noux_routing 40%] [image sculpt_20_08_system_shell_routing 40%]
Each choice represents a connection to a system resource of a particular type. Each choice represents a connection to a system resource of a particular type.
Initially, the presented options are resources that are built-in into Sculpt's Initially, the presented options are resources that are built-in into Sculpt's
@ -731,7 +746,7 @@ The base system provides three different GUI options.
:keyboard focus: grants control over the keyboard focus. It should be :keyboard focus: grants control over the keyboard focus. It should be
assigned to only one component, typically a window manager. However, assigned to only one component, typically a window manager. However,
in principle, another component like _noux-system_ can be connected in principle, another component like the _system shell_ can be connected
to it and thereby becomes able to receive keyboard input. to it and thereby becomes able to receive keyboard input.
:desktop lock screen: assigns the component the role of a lock screen. Once :desktop lock screen: assigns the component the role of a lock screen. Once
@ -854,8 +869,8 @@ The Sculpt base system has two built-in file systems.
The two built-in file systems reside in memory. In order to access persistent The two built-in file systems reside in memory. In order to access persistent
storage, additional file-system services can be started as regular components storage, additional file-system services can be started as regular components
within the runtime subsystem. Those components, in turn, need to be connected to within the runtime subsystem. Those components, in turn, need to be connected
the corresponding block devices. to the corresponding block devices.
:used file system: is the file system selected for the use of Sculpt. :used file system: is the file system selected for the use of Sculpt.
In principle, the specific file system such as "usb-1-10.3.fs" can be In principle, the specific file system such as "usb-1-10.3.fs" can be
@ -990,6 +1005,22 @@ audio infrastructure like drivers and a mixer can be installed as regular
components. components.
CPU-resource assignment
~~~~~~~~~~~~~~~~~~~~~~~
[image sculpt_20_08_affinity 40%]
You may already have noticed the additional item "Resource assignment ..."
in the component-configuration dialog (Figure [sculpt_20_08_affinity]).
It leads to a sub menu for restricting
the CPU usage of the new component. The configuration dialog shows a matrix of
CPU cores where the x-axis denotes the physical cores and the y-axis the
hyperthreads. By default, all available CPU cores are selected. You can toggle
the nodes by clicking on them. The dialog ensures that the selection is always
a rectangular area. So one click may affect nodes other than only the clicked
one.
Runtime management Runtime management
================== ==================
@ -999,10 +1030,9 @@ In contrast to the drivers subsystem and the Leitzentrale, which have a
predefined purpose, the runtime subsystem is shaped by the user. The predefined purpose, the runtime subsystem is shaped by the user. The
components present in the runtime subsystem are displayed by the components view. components present in the runtime subsystem are displayed by the components view.
Some of them are managed by the Leitzentrale. For example, while inspecting a Some of them are managed by the Leitzentrale. For example, while inspecting a
file system, the corresponding "inspect", "inspect_terminal", and file system, the corresponding "inspect" component appear automatically. Other
"inspect_noux" components appear automatically. Other components correspond to components correspond to subsystems deployed from installed packages, in
subsystems deployed from installed packages, in particular the ones created particular the ones created via the "+" menu.
via the "+" menu.
The current configuration of the runtime subsystem is available at the The current configuration of the runtime subsystem is available at the
_config_ file system at _managed/runtime_. It is not recommended to modify _config_ file system at _managed/runtime_. It is not recommended to modify
@ -1094,8 +1124,8 @@ Depending on the operation selected by the user, the Sculpt manager will
automatically spawn helper components in the runtime to perform the selected automatically spawn helper components in the runtime to perform the selected
operation. operation.
For example, by selecting the "Format device" operation, the Sculpt manager For example, by selecting the "Format device" operation, the Sculpt manager
will create a noux instance with the selected block device mounted at will create a tiny Unix-like subsystem with the selected block device mounted at
'/dev/block' and e2fsprogs mounted at '/'. The noux instance runs '/dev/block' and e2fsprogs mounted at '/'. This Unix-like subsystem runs
'mkfs.ext2' as init process. Likewise, an existing EXT2 file system 'mkfs.ext2' as init process. Likewise, an existing EXT2 file system
can be checked by activating the "Check" button, which triggers the execution can be checked by activating the "Check" button, which triggers the execution
of 'fsck.ext2' for the selected file system. of 'fsck.ext2' for the selected file system.
@ -1220,18 +1250,18 @@ a free download at [https://genode.org].
! git clone https://github.com/genodelabs/genode.git ! git clone https://github.com/genodelabs/genode.git
! cd genode ! cd genode
! git checkout -b sculpt-20.02 sculpt-20.02 ! git checkout -b sculpt-20.08 sculpt-20.08
# Download the support for the NOVA microkernel # Download the support for the NOVA microkernel
! ./tool/depot/download genodelabs/bin/x86_64/base-nova/2020-02-27 ! ./tool/depot/download genodelabs/bin/x86_64/base-nova/2020-09-17
The content is downloaded to the _public/_ directory and extracted to The content is downloaded to the _public/_ directory and extracted to
the _depot/_ directory. the _depot/_ directory.
# Download all ingredients for the Sculpt boot image # Download all ingredients for the Sculpt boot image
! ./tool/depot/download genodelabs/pkg/x86_64/sculpt/2020-03-09 ! ./tool/depot/download genodelabs/pkg/x86_64/sculpt/2020-09-17
# Create a build directory # Create a build directory
@ -1425,8 +1455,8 @@ Device drivers
_(used by the VESA driver)_ _(used by the VESA driver)_
Programs and libraries used within the noux runtime Programs and libraries used within the Unix-like subsystems
--------------------------------------------------- -----------------------------------------------------------
:Vim: :Vim:
[http://www.vim.org] [http://www.vim.org]
@ -1472,6 +1502,9 @@ Libraries used for the package-management infrastructure
[https://www.gnupg.org] [https://www.gnupg.org]
_(basis of the verify tool)_ _(basis of the verify tool)_
:Jitterentropy RNG:
[https://chronox.de/jent.html]
Applications Applications
------------ ------------