Puppet module to manage Rust with rustup

This manages Rust installations with the rustup tool. There are two ways to use it:

• Per-user installations. Each user has their own installation in their home directory that is entirely separate from every other installation. This is how the rustup tool expects to be used.
• Global installation. Users are able to access shared toolchains and targets, but will not be able to change any of them. Users can still use cargo install, but the installed tools will only be accessible to themselves. The rustup tool is not designed to be used this way, but it seems to work fine.

Usage

Per-user installation

You can just use the rustup defined type, or you can define separate resources for toolchains and targets. You can mix and match these approaches if you want.

To just install the standard, stable toolchain:

rustup { 'user':
  toolchains => ['stable'],
}

A more complicated example:

rustup { 'user':
  toolchains       => ['stable', 'nightly'],
  targets          => [
    'default stable',
    'default nightly',
    'x86_64-unknown-linux-musl nightly',
  ],
  purge_toolchains => true,
  purge_targets    => true,
}

This is the multi-resource equivalent of the above, but it always tries to install the latest nightly toolchain:

rustup { 'user':
  purge_toolchains => true,
  purge_targets    => true,
}
rustup::toolchain { 'user: stable': }
rustup::target { 'user: default': }
rustup::toolchain { 'user: nightly':
  ensure => latest,
}
rustup::target { 'user: default nightly': }
rustup::target { 'user: x86_64-unknown-linux-musl nightly': }

You can find more information in the reference documentation for rustup::toolchain and rustup::target.

Global installation

Like the per-user installation this can be configured with one resource (the rustup::global class) or multiple. Multiple resources provide more configurability.

class { 'rustup::global':
  toolchains       => ['stable', 'nightly'],
  targets          => [
    'default stable',
    'default nightly',
    'x86_64-unknown-linux-musl nightly',
  ],
  purge_toolchains => true,
  purge_targets    => true,
}

Again, the equivalent configuration except that the nightly toolchain is updated every run:

class { 'rustup::global':
  purge_toolchains => true,
  purge_targets    => true,
}
rustup::global::toolchain { 'stable': }
rustup::global::target { 'default': }
rustup::global::toolchain { 'nightly':
  ensure => latest,
}
rustup::global::target { 'default nightly': }
rustup::global::target { 'x86_64-unknown-linux-musl nightly': }

You can find more information in the reference documentation for rustup::global::toolchain and rustup::global::target.

Limitations

• This does not allow management of components.
• This does not support Windows.

Development status

This is presently being developed, if in a somewhat intermittent fashion.

Reference

See REFERENCE.md.

Development

See DEVELOPMENT.md.

Reference

Table of Contents

Classes

• rustup::global: Manage global Rust installation with rustup

Defined types

• rustup: Manage a user’s Rust installation with rustup
• rustup::exec: Run a rustup command
• rustup::global::target: Install a target for a toolchain for global installation
• rustup::global::toolchain: Install a toolchain for global installation
• rustup::target: Install a target for a toolchain
• rustup::toolchain: Install a toolchain

Resource types

Private Resource types

• rustup_internal: Manage a user’s Rust installation with rustup

Functions

Private Functions

• rustup::home: Return the default home directory for a user on this OS

Data types

• Rustup::OptionalStringOrArray: Convenience type to make params easier to read
• Rustup::Profile: Profile for toolchain installation

Classes

rustup::global

Manage global Rust installation with rustup

Examples

Standard usage

include rustup::global

Parameters

The following parameters are available in the rustup::global class:

• ensure
• user
• manage_user
• purge_toolchains
• purge_targets
• dist_server
• home
• shell
• env_scripts_append
• env_scripts_create
• installer_source

ensure

Data type: Enum[present, latest, absent]

• present - install rustup, but don’t update it.
• latest - install rustup and update it on every puppet run.
• absent - uninstall rustup and the tools it manages.

Default value: present

user

Data type: String[1]

The user to own and manage rustup. We recommend not using root or any other existing user.

Default value: 'rustup'

manage_user

Data type: Boolean

Whether or not to manage $user user.

Default value: true

purge_toolchains

Data type: Boolean

Whether or not to uninstall toolchains that aren’t managed by Puppet.

Default value: false

purge_targets

Data type: Boolean

Whether or not to uninstall targets that aren’t managed by Puppet.

Default value: false

dist_server

Data type: Optional[Stdlib::HTTPUrl]

Override RUSTUP_DIST_SERVER. Set to 'https://dev-static.rust-lang.org' to install pre-release toolchains.

Default value: undef

home

Data type: Stdlib::Absolutepath

Where to install rustup and the rust toolchains. Will contain rustup and cargo directories.

Default value: '/opt/rust'

shell

Data type: Stdlib::Absolutepath

Shell for the rustup user. This can be a nologin shell.

Default value: '/bin/bash'

env_scripts_append

Data type: Array[Stdlib::Absolutepath]

Scripts to append with line that sources the cargo environment script.

Default value: ['/etc/bashrc']

env_scripts_create

Data type: Array[Stdlib::Absolutepath]

Paths that will get links to the cargo environment script.

Default value:

$facts['os']['family'] ? {
    'Darwin' => [],
    default  => ['/etc/profile.d/99-cargo.sh']

installer_source

Data type: Stdlib::HTTPUrl

URL of the rustup installation script. Changing this will have no effect after the initial installation.

Default value: 'https://sh.rustup.rs'

Defined types

rustup

The name should be the username.

Examples

Standard usage

rustup { 'daniel': }

Parameters

The following parameters are available in the rustup defined type:

• ensure
• user
• default_toolchain
• toolchains
• purge_toolchains
• targets
• purge_targets
• dist_server
• home
• rustup_home
• cargo_home
• modify_path
• installer_source

ensure

Data type: Enum[present, latest, absent]

• present - install rustup, but don’t update it.
• latest - install rustup and update it on every puppet run.
• absent - uninstall rustup and the tools it manages.

Default value: present

user

Data type: String[1]

The user to own and manage rustup.

Default value: $name

default_toolchain

Data type: Optional[String[1]]

Which toolchain should be the default.

Default value: undef

toolchains

Data type: Array[String[1]]

The toolchains to install.

Default value: []

purge_toolchains

Data type: Boolean

Whether or not to uninstall toolchains that aren’t managed by Puppet.

Default value: false

targets

Data type: Array[String[1]]

The targets to install. These can take two forms:

• "$target $toolchain": Install $target for $toolchain.
• "$target": Install $target for the default toolchain.

You can use 'default' to indicate the target for the current host.

Default value: []

purge_targets

Data type: Boolean

Whether or not to uninstall targets that aren’t managed by Puppet.

Default value: false

dist_server

Data type: Optional[Stdlib::HTTPUrl]

Override RUSTUP_DIST_SERVER. Set to 'https://dev-static.rust-lang.org' to install pre-release toolchains.

Default value: undef

home

Data type: Stdlib::Absolutepath

The user’s home directory. This defaults to /home/$user on Linux and /Users/$user on macOS.

Default value: rustup::home($user)

rustup_home

Data type: Stdlib::Absolutepath

Where toolchains are installed. Generally you shouldn’t change this.

Default value: "${home}/.rustup"

cargo_home

Data type: Stdlib::Absolutepath

Where cargo installs executables. Generally you shouldn’t change this.

Default value: "${home}/.cargo"

modify_path

Data type: Boolean

Whether or not to let rustup modify the user’s PATH in their shell init scripts. This only affects the initial installation and removal.

Default value: true

installer_source

Data type: Stdlib::HTTPUrl

URL of the rustup installation script. Changing this will have no effect after the initial installation.

Default value: 'https://sh.rustup.rs'

rustup::exec

The name should start with the username followed by a colon and a space, then the command. For example:

rustup::exec { 'daniel: rustup default nightly': }

Parameters

The following parameters are available in the rustup::exec defined type:

• user
• command
• creates
• environment
• onlyif
• refreshonly
• unless
• home
• rustup_home
• cargo_home
• bin
• more

user

Data type: String[1]

The user to run as. Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(': ')[0]

command

Data type: String[1]

The command to run, e.g. 'rustup default stable'. Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(': ')[1]

creates

Data type: Optional[String[1]]

Only run when if this path does not exist. (See exec documentation.)

Default value: undef

environment

Data type: Array[String[1]]

Additional environment variables to set beyond RUSTUP_HOME, CARGO_HOME, and PATH.

Default value: []

onlyif

Data type: Rustup::OptionalStringOrArray

Only run when $onlyif returns success. (See exec documentation.)

Default value: undef

refreshonly

Data type: Boolean

Only run this when it receives an event. (See exec documentation.)

Default value: false

unless

Data type: Rustup::OptionalStringOrArray

Only run when $unless returns failure. (See exec documentation.)

Default value: undef

home

Data type: Stdlib::Absolutepath

The user’s home directory. This defaults to /home/$user on Linux and /Users/$user on macOS. This is only used to calculate defaults for the $rustup_home and $cargo_home parameters.

Default value: rustup::home($user)

rustup_home

Data type: Stdlib::Absolutepath

Where toolchains are installed. Generally you shouldn’t change this.

Default value: "${home}/.rustup"

cargo_home

Data type: Stdlib::Absolutepath

Where cargo installs executables. Generally you shouldn’t change this.

Default value: "${home}/.cargo"

bin

Data type: Stdlib::Absolutepath

Where rustup installs proxy executables. Generally you shouldn’t change this.

Default value: "${cargo_home}/bin"

more

Data type: Hash[String[1], Any]

Other parameters to pass to exec. They may override any of the other parameters.

Default value: {}

rustup::global::target

You can name this two ways to automatically set the parameters:

• "$target $toolchain": install $target for $toolchain in the global installation. For example, 'x86_64-unknown-linux-gnu nightly'.
• "$target": install $target for the default toolchain in the global installation. For example: 'stable'.

Parameters

The following parameters are available in the rustup::global::target defined type:

• ensure
• target
• toolchain

ensure

Data type: Enum[present, absent]

Whether the target should be present or absent.

Default value: present

target

Data type: String[1]

The name of the target to install, e.g. "sparcv9-sun-solaris". Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(' ')[0]

toolchain

Data type: Optional[String[1]]

The name of the toolchain in which to install the target, e.g. "stable". undef means the default toolchain. Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(' ')[1]

rustup::global::toolchain

The name should just be the toolchain. For example:

rustup::global::toolchain { 'stable': }

Parameters

The following parameters are available in the rustup::global::toolchain defined type:

• ensure
• toolchain
• profile

ensure

Data type: Enum[present, latest, absent]

• present - install toolchain if it doesn’t exist, but don’t update it.
• latest - install toolchain and update it on every puppet run.
• absent - uninstall toolchain.

Default value: present

toolchain

Data type: String[1]

The name of the toolchain to install, e.g. "stable".

Default value: $name

profile

Data type: Rustup::Profile

Profile to use for installation. This determines which components will be installed initially.

Changing this for an existing installation will not have an effect even if it causes an update, i.e. when ensure => latest is set.

Default value: 'default'

rustup::target

You can name this two ways to automatically set the parameters:

• "$rustup: $target $toolchain": install $target for $toolchain for the rustup resource named $rustup (normally the username). For example, 'daniel: x86_64-unknown-linux-gnu nightly'.
• "$rustup: $target": install $target for the default toolchain for the rustup resource named $rustup (normally the username). For example: 'daniel: stable'.

You may use the string 'default' as the target to indicate the target that corresponds to the current host.

Parameters

The following parameters are available in the rustup::target defined type:

• ensure
• rustup
• target
• toolchain

ensure

Data type: Enum[present, absent]

Whether the target should be present or absent.

Default value: present

rustup

Data type: String[1]

The name of the rustup installation (normally the username). Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(': ')[0]

target

Data type: String[1]

The name of the target to install, e.g. "sparcv9-sun-solaris". Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(': ')[1].split(' ')[0]

toolchain

Data type: Optional[String[1]]

The name of the toolchain in which to install the target, e.g. "stable". undef means the default toolchain. Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(': ')[1].split(' ')[1]

rustup::toolchain

The name should start with the name of the rustup resource (normally the name of the user) followed by a colon and a space, then the toolchain. For example:

rustup::toolchain { 'daniel: stable': }

Parameters

The following parameters are available in the rustup::toolchain defined type:

• ensure
• rustup
• toolchain
• profile

ensure

Data type: Enum[present, latest, absent]

• present - install toolchain if it doesn’t exist, but don’t update it.
• latest - install toolchain and update it on every puppet run.
• absent - uninstall toolchain.

Default value: present

rustup

Data type: String[1]

The name of the rustup installation (normally the username). Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(': ')[0]

toolchain

Data type: String[1]

The name of the toolchain to install, e.g. "stable". Automatically set if the $name of the resource follows the rules above.

Default value: $name.split(': ')[1]

profile

Data type: Rustup::Profile

Profile to use for installation. This determines which components will be installed initially.

Changing this for an existing installation will not have an effect even if it causes an update, i.e. when ensure => latest is set.

Default value: 'default'

Data types

Rustup::OptionalStringOrArray

Convenience type to make params easier to read

Alias of Variant[Undef, String[1], Array[String[1]]]

Rustup::Profile

default is a keyword in Puppet, so it must always be wrapped in quotes.

Alias of Enum[minimal, 'default', complete]

Change log

All notable changes to this project will be documented in this file.

Release 0.2.6

• Synced with PDK.

Release 0.2.5

• Fixed initial installation on macOS to always use the native architecture… for real this time (the previous attempt ended up being a no-op). Thanks again to Zac Bentley for fixing the issue.
• Fixed defaults for rustup::global on macOS so that it doesn’t try to add a link to the non-existent /etc/profile.d.

Release 0.2.4

• Changed initial installation on macOS to always use the native architecture. This avoids performance issues when Puppet is run in x86_64 emulation mode (Rosetta) on ARM (e.g. when run from Bolt). Thanks to Zac Bentley for finding and fixing the issue.
• Synced with PDK.

Release 0.2.3

• Synced with PDK.

Release 0.2.2

• Fixed Puppet 8 support (shell_escape() must now be called stdlib::shell_escape()).
• Updated automatic PR checks to run acceptance tests with both Puppet 7 and Puppet 8 (Puppet 6 is still supported by this module, but unfortunately the acceptance test framework does not support it).

Release 0.2.1

• Added a section about development status (in slow progress) to README.md.
• Updated metadata to support Puppet 8.
• Synced with PDK.

Release 0.2.0

Features

• Added profile parameter to select which components to include on the initial installation of a toolchain. (PR #10)
• Added option to install pre-release toolchains. (PR #11)
• Added option to make tracing rustup commands easier. (PR #13)

Bug fixes

• Now supports installing non-host toolchains for use with emulators. For example, it is now possible to install the x86_64-pc-windows-gnu toolchain on a Linux host without warnings. (PR #9)
• Fixed default values and anchor links in REFERENCE.md. (PR #14, PR #15, PR #20)

Release 0.1.0

Features

• Install Rust via rustup.