#52 rewrite 'using modules'
Merged 4 months ago by asamalik. Opened 4 months ago by asamalik.
fedora-docs/ asamalik/modularity switching-stremas  into  master

@@ -1,62 +1,75 @@ 

  = Using Modules in Fedora


- ++++

- <iframe width="560" height="315" src="https://www.youtube.com/embed/oNynHOMTV_0?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>

- ++++

+ Modularity is a mechanism of making multiple versions of software available to your system.


- From the user perspective, modules are like release-independent package groups on independent life cycles, providing alternative streams of content to Fedora.

+ **Modules** are special package groups usually representing an application, a language runtime, or a set of tools. They are available in one or **multiple streams** which usually represent a major version of a piece of software, giving you an option to choose what versions of packages you want to consume.


- == Enable modular repositories

+ To simplify installation, modules usually define one or more **installation profiles** that represent a specific use case. For example a `server` or a `client` profile in a database module.


- If you are running the Fedora Server Edition, the Modular Repository should already be enabled.

- However, if you are using a container or a different Edition, you need to:

+ And because having too many choices might be overwhelming, Fedora ships with a set of module **defaults** — so you only need to make choices when desired. 


-     # dnf install fedora-repos-modular

+ Finally, because big changes are not always welcome, Modularity has been built in a way it can be basically invisible to the user. The usual installation commands continue to work — so packages with a default stream can be installed the same way as before regardles of them being modularized or not.


- == Supported / Unsupported Package Managers

+ == Discovering content


- * Supported

- ** dnf

- ** dnfdragora

- * Unsupported (if unlisted, assume unsupported)

- ** microdnf

- ** PackageKit

- ** Gnome Software

- ** Apper

- ** Cockpit

+ === Listing packages


- Using an unsupported Package Manager for *any* reason with modules enabled has serious potential to break things.

- People are working on the above list of Unsupported package managers primarily by including module support in libdnf.

- If you are interested in adding module support to a different package manager, please contact the https://github.com/rpm-software-management/dnf[dnf team].

+ Packages available to the system can be discovered by the usual commands such as `dnf search NAME`, `dnf list NAME`, or by using the `dnf repoquery QUERY` command for more complex queries. However, it is important to note that those commands will, apart from traditional packages, only list modular packages coming from a _default_ or an _enabled_ module stream.


- == List available modules

+ === Listing modules


- To list all available modules and their streams, run the following command:

+ To list modules available to your system, and to see what streams are _default_ or have been _enabled_, use the following command:


      $ dnf module list


- == Install a module

+ == Consuming content


- To install a module, use the `name:stream/profile` syntax, for example:

+ === Installing packages


-     $ dnf module install nodejs:6/default

+ Packages can be installed the usual way by running the `dnf install NAME` command. Any traditional package, or a modular package coming from a _default_ or an _enabled_ module can be installed this way.


- Alternatively, you can also enable a module and then install RPM packages directly:

+ Packages from other module streams can be consumed by either _enabling a module_ stream and then installing individual packages, or by _installing a module_ directly.


-     $ dnf module enable nodejs:6

-     $ dnf install nodejs

+ === Enabling modules


- == Changing a stream

+ To **enable a module stream** and make its packages available for installation, run the following command:


- To change a stream of a module that has been already installed, use the installation command. For example:

+     $ dnf module enable NAME:STREAM


-     $ dnf module install nodejs:9/default

+ For example, to make Node.js 8 packages available for installation, run:


- == Module defaults

+     $ dnf module enable nodejs:8


- We are currently working on _system profiles_ — the defaults for your system.

- Thanks to these, you will need to be specific about the module, stream, or profile only when you need to. When implemented, all the following commands will also work:

+ Packages from enabled module streams can be then installed by the `dnf install NAME` command.


-     $ dnf install nodejs            # installs a nodejs RPM package from the default stream

-     $ dnf module install nodejs     # installs the default profile from the default stream

-     $ dnf module install nodejs:9   # installs the default profile from the 9 stream

+ === Installing modules


+ To install a module, use one of the following commands. Not specifying a _stream_ or a _profile_ causes DNF to choose the _default_. However, not every module has a _default stream_ or _default profile_.


+     $ dnf module install NAME

+     $ dnf module install NAME:STREAM

+     $ dnf module install NAME/PROFILE

+     $ dnf module install NAME:STREAM/PROFILE


+ For example, to install the Node.js 8 runtime and the client tooling of the default stream of MongoDB, run:


+     $ dnf module install nodejs:8

+     $ dnf module install mongodb/client


+ === Switching module streams


+ NOTE: Switching streams is a risky operation that might not be always supported in packages, especially downgrades. 


+ Switching to a different stream than the one that is installed on a system is a two-step process. First, the current stream needs to be reset causing it not to be enabled anymore — this will however keep its packages installed. Second, a new stream needs to be installed.


+     $ dnf module reset NAME

+     $ dnf module install NAME:STREAM


+ For example, to switch from Node.js 8 to Node.js 10, run:


+     $ dnf module reset nodejs

+     $ dnf module install nodejs:10


+ == Updating the system


+ Updating a system by running the `dnf update` command causes all packages to be upgraded to their latest version provided by their module stream. 

\ No newline at end of file

I might change to "so packages with a default stream can be installed the same way as before".

This link doesn't render correctly in the preview.

Actually, we should probably leave unofficial tools out of the official documentation. Put that in a blog post somewhere instead.

There is no "p" in our "ackages". Part of me wants to keep it that way...

For clarity, say the "client tooling of the default stream of MongoDB" here.

We should probably make it clear that switching streams is a risky operation and that it isn't guaranteed to work for package downgrades.

Drop the bit about the stream never being switched automatically, since that may not be true for distro upgrades if they're following the default stream.

1 new commit added

  • few corrections on the 'using modules' page
4 months ago

Pull-Request has been merged by asamalik

4 months ago