# Reference

<!-- DO NOT EDIT: This document was generated by Puppet Strings -->

## Table of Contents

### Classes

* [`rustup::global`](#rustup__global): Manage global Rust installation with `rustup`

### Defined types

* [`rustup`](#rustup): Manage a user’s Rust installation with `rustup`
* [`rustup::exec`](#rustup__exec): Run a `rustup` command
* [`rustup::global::target`](#rustup__global__target): Install a target for a toolchain for global installation
* [`rustup::global::toolchain`](#rustup__global__toolchain): Install a toolchain for global installation
* [`rustup::target`](#rustup__target): Install a target for a toolchain
* [`rustup::toolchain`](#rustup__toolchain): Install a toolchain

### Resource types

* [`rustup_internal`](#rustup_internal): Manage a user’s Rust installation with `rustup`

### Functions

* [`rustup::home`](#rustup__home): Return the default home directory for a user on this OS

### Data types

* [`Rustup::OptionalStringOrArray`](#Rustup__OptionalStringOrArray): Convenience type to make params easier to read
* [`Rustup::Profile`](#Rustup__Profile): Profile for toolchain installation

## Classes

### <a name="rustup__global"></a>`rustup::global`

Manage global Rust installation with `rustup`

#### Examples

##### Standard usage

```puppet
include rustup::global
```

#### Parameters

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

* [`ensure`](#rustup__global___ensure)
* [`user`](#rustup__global___user)
* [`manage_user`](#rustup__global___manage_user)
* [`purge_toolchains`](#rustup__global___purge_toolchains)
* [`purge_targets`](#rustup__global___purge_targets)
* [`dist_server`](#rustup__global___dist_server)
* [`home`](#rustup__global___home)
* [`shell`](#rustup__global___shell)
* [`env_scripts_append`](#rustup__global___env_scripts_append)
* [`env_scripts_create`](#rustup__global___env_scripts_create)
* [`installer_source`](#rustup__global___installer_source)

##### <a name="rustup__global___ensure"></a>`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`

##### <a name="rustup__global___user"></a>`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'`

##### <a name="rustup__global___manage_user"></a>`manage_user`

Data type: `Boolean`

Whether or not to manage `$user` user.

Default value: ``true``

##### <a name="rustup__global___purge_toolchains"></a>`purge_toolchains`

Data type: `Boolean`

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

Default value: ``false``

##### <a name="rustup__global___purge_targets"></a>`purge_targets`

Data type: `Boolean`

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

Default value: ``false``

##### <a name="rustup__global___dist_server"></a>`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``

##### <a name="rustup__global___home"></a>`home`

Data type: `Stdlib::Absolutepath`

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

Default value: `'/opt/rust'`

##### <a name="rustup__global___shell"></a>`shell`

Data type: `Stdlib::Absolutepath`

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

Default value: `'/bin/bash'`

##### <a name="rustup__global___env_scripts_append"></a>`env_scripts_append`

Data type: `Array[Stdlib::Absolutepath]`

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

Default value: `['/etc/bashrc']`

##### <a name="rustup__global___env_scripts_create"></a>`env_scripts_create`

Data type: `Array[Stdlib::Absolutepath]`

Paths that will get links to the cargo environment script.

Default value: `['/etc/profile.d/99-cargo.sh']`

##### <a name="rustup__global___installer_source"></a>`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

### <a name="rustup"></a>`rustup`

The name should be the username.

#### Examples

##### Standard usage

```puppet
rustup { 'daniel': }
```

#### Parameters

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

* [`ensure`](#rustup___ensure)
* [`user`](#rustup___user)
* [`default_toolchain`](#rustup___default_toolchain)
* [`toolchains`](#rustup___toolchains)
* [`purge_toolchains`](#rustup___purge_toolchains)
* [`targets`](#rustup___targets)
* [`purge_targets`](#rustup___purge_targets)
* [`dist_server`](#rustup___dist_server)
* [`home`](#rustup___home)
* [`rustup_home`](#rustup___rustup_home)
* [`cargo_home`](#rustup___cargo_home)
* [`modify_path`](#rustup___modify_path)
* [`installer_source`](#rustup___installer_source)

##### <a name="rustup___ensure"></a>`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`

##### <a name="rustup___user"></a>`user`

Data type: `String[1]`

The user to own and manage rustup.

Default value: `$name`

##### <a name="rustup___default_toolchain"></a>`default_toolchain`

Data type: `Optional[String[1]]`

Which toolchain should be the default.

Default value: ``undef``

##### <a name="rustup___toolchains"></a>`toolchains`

Data type: `Array[String[1]]`

The toolchains to install.

Default value: `[]`

##### <a name="rustup___purge_toolchains"></a>`purge_toolchains`

Data type: `Boolean`

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

Default value: ``false``

##### <a name="rustup___targets"></a>`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: `[]`

##### <a name="rustup___purge_targets"></a>`purge_targets`

Data type: `Boolean`

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

Default value: ``false``

##### <a name="rustup___dist_server"></a>`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``

##### <a name="rustup___home"></a>`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)`

##### <a name="rustup___rustup_home"></a>`rustup_home`

Data type: `Stdlib::Absolutepath`

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

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

##### <a name="rustup___cargo_home"></a>`cargo_home`

Data type: `Stdlib::Absolutepath`

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

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

##### <a name="rustup___modify_path"></a>`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``

##### <a name="rustup___installer_source"></a>`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'`

### <a name="rustup__exec"></a>`rustup::exec`

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

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

[`exec`]: https://puppet.com/docs/puppet/latest/types/exec.html

#### Parameters

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

* [`user`](#rustup__exec___user)
* [`command`](#rustup__exec___command)
* [`creates`](#rustup__exec___creates)
* [`environment`](#rustup__exec___environment)
* [`onlyif`](#rustup__exec___onlyif)
* [`refreshonly`](#rustup__exec___refreshonly)
* [`unless`](#rustup__exec___unless)
* [`home`](#rustup__exec___home)
* [`rustup_home`](#rustup__exec___rustup_home)
* [`cargo_home`](#rustup__exec___cargo_home)
* [`bin`](#rustup__exec___bin)
* [`more`](#rustup__exec___more)

##### <a name="rustup__exec___user"></a>`user`

Data type: `String[1]`

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

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

##### <a name="rustup__exec___command"></a>`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: `split($name, ': ')[1]`

##### <a name="rustup__exec___creates"></a>`creates`

Data type: `Optional[String[1]]`

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

Default value: ``undef``

##### <a name="rustup__exec___environment"></a>`environment`

Data type: `Array[String[1]]`

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

Default value: `[]`

##### <a name="rustup__exec___onlyif"></a>`onlyif`

Data type: `Rustup::OptionalStringOrArray`

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

Default value: ``undef``

##### <a name="rustup__exec___refreshonly"></a>`refreshonly`

Data type: `Boolean`

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

Default value: ``false``

##### <a name="rustup__exec___unless"></a>`unless`

Data type: `Rustup::OptionalStringOrArray`

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

Default value: ``undef``

##### <a name="rustup__exec___home"></a>`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)`

##### <a name="rustup__exec___rustup_home"></a>`rustup_home`

Data type: `Stdlib::Absolutepath`

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

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

##### <a name="rustup__exec___cargo_home"></a>`cargo_home`

Data type: `Stdlib::Absolutepath`

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

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

##### <a name="rustup__exec___bin"></a>`bin`

Data type: `Stdlib::Absolutepath`

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

Default value: `"${cargo_home}/bin"`

##### <a name="rustup__exec___more"></a>`more`

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

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

Default value: `{}`

### <a name="rustup__global__target"></a>`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`](#rustup__global__target___ensure)
* [`target`](#rustup__global__target___target)
* [`toolchain`](#rustup__global__target___toolchain)

##### <a name="rustup__global__target___ensure"></a>`ensure`

Data type: `Enum[present, absent]`

Whether the target should be present or absent.

Default value: `present`

##### <a name="rustup__global__target___target"></a>`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: `split($name, ' ')[0]`

##### <a name="rustup__global__target___toolchain"></a>`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: `split($name, ' ')[1]`

### <a name="rustup__global__toolchain"></a>`rustup::global::toolchain`

The name should just be the toolchain. For example:

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

#### Parameters

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

* [`ensure`](#rustup__global__toolchain___ensure)
* [`toolchain`](#rustup__global__toolchain___toolchain)
* [`profile`](#rustup__global__toolchain___profile)

##### <a name="rustup__global__toolchain___ensure"></a>`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`

##### <a name="rustup__global__toolchain___toolchain"></a>`toolchain`

Data type: `String[1]`

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

Default value: `$name`

##### <a name="rustup__global__toolchain___profile"></a>`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'`

### <a name="rustup__target"></a>`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___ensure)
* [`rustup`](#rustup__target___rustup)
* [`target`](#rustup__target___target)
* [`toolchain`](#rustup__target___toolchain)

##### <a name="rustup__target___ensure"></a>`ensure`

Data type: `Enum[present, absent]`

Whether the target should be present or absent.

Default value: `present`

##### <a name="rustup__target___rustup"></a>`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: `split($name, ': ')[0]`

##### <a name="rustup__target___target"></a>`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: `split(split($name, ': ')[1], ' ')[0]`

##### <a name="rustup__target___toolchain"></a>`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: `split(split($name, ': ')[1], ' ')[1]`

### <a name="rustup__toolchain"></a>`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:

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

#### Parameters

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

* [`ensure`](#rustup__toolchain___ensure)
* [`rustup`](#rustup__toolchain___rustup)
* [`toolchain`](#rustup__toolchain___toolchain)
* [`profile`](#rustup__toolchain___profile)

##### <a name="rustup__toolchain___ensure"></a>`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`

##### <a name="rustup__toolchain___rustup"></a>`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: `split($name, ': ')[0]`

##### <a name="rustup__toolchain___toolchain"></a>`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: `split($name, ': ')[1]`

##### <a name="rustup__toolchain___profile"></a>`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'`

## Resource types

### <a name="rustup_internal"></a>`rustup_internal`

Use the [`rustup`](#rustup) defined type instead of this.

The name should be the username.

**Autorequires:**
  * The `user`.
  * The directory specified by `home`.
  * The directory specified by `cargo_home` and its parent.
  * The directory specified by `rustup_home` and its parent.

#### Properties

The following properties are available in the `rustup_internal` type.

##### `default_toolchain`

Which toolchain should be default.

##### `ensure`

Valid values: `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`

##### `targets`

The targets to install or remove.

Each target must be a Hash with three entries:
  * `ensure`: one of `present` or `absent`
  * `target`: the name of the target
  * `toolchain`: the name of the toolchain or `undef` to indicate the
    default toolchain

##### `toolchains`

The toolchains to install, update, or remove.

Each toolchain must be a Hash with two entries:
  * `ensure`: one of `present`, `latest`, or `absent`
  * `toolchain`: the name of the toolchain
  * `profile`: one of `minimal`, `default`, or `complete`

#### Parameters

The following parameters are available in the `rustup_internal` type.

* [`cargo_home`](#rustup_internal___cargo_home)
* [`dist_server`](#rustup_internal___dist_server)
* [`home`](#rustup_internal___home)
* [`installer_source`](#rustup_internal___installer_source)
* [`modify_path`](#rustup_internal___modify_path)
* [`provider`](#rustup_internal___provider)
* [`purge_targets`](#rustup_internal___purge_targets)
* [`purge_toolchains`](#rustup_internal___purge_toolchains)
* [`rustup_home`](#rustup_internal___rustup_home)
* [`user`](#rustup_internal___user)

##### <a name="rustup_internal___cargo_home"></a>`cargo_home`

Where `cargo` installs executables (autorequired). Generally you shouldn’t
change this.

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

##### <a name="rustup_internal___dist_server"></a>`dist_server`

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

##### <a name="rustup_internal___home"></a>`home`

The user’s home directory (autorequired).

Default value: `"/home/${user}"`

##### <a name="rustup_internal___installer_source"></a>`installer_source`

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

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

##### <a name="rustup_internal___modify_path"></a>`modify_path`

Valid values: ``true``, ``false``, `yes`, `no`

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``

##### <a name="rustup_internal___provider"></a>`provider`

The specific backend to use for this `rustup_internal` resource. You will seldom need to specify this --- Puppet will
usually discover the appropriate provider for your platform.

##### <a name="rustup_internal___purge_targets"></a>`purge_targets`

Valid values: ``true``, ``false``, `yes`, `no`

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

Default value: ``true``

##### <a name="rustup_internal___purge_toolchains"></a>`purge_toolchains`

Valid values: ``true``, ``false``, `yes`, `no`

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

Default value: ``true``

##### <a name="rustup_internal___rustup_home"></a>`rustup_home`

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

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

##### <a name="rustup_internal___user"></a>`user`

namevar

The user that owns this instance of `rustup` (autorequired).

## Functions

### <a name="rustup__home"></a>`rustup::home`

Type: Puppet Language

Return the default home directory for a user on this OS

#### `rustup::home(String[1] $user)`

Return the default home directory for a user on this OS

Returns: `Stdlib::Absolutepath` The path to the home directory.

##### `user`

Data type: `String[1]`

The name of the user.

## Data types

### <a name="Rustup__OptionalStringOrArray"></a>`Rustup::OptionalStringOrArray`

Convenience type to make params easier to read

Alias of

```puppet
Variant[Undef, String[1], Array[String[1]]]
```

### <a name="Rustup__Profile"></a>`Rustup::Profile`

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

Alias of

```puppet
Enum[minimal, 'default', complete]
```