You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To share your module with other Puppet users, get contributions to your modules, and maintain your module releases, publish your module on the Puppet Forge. The Forge is a community repository of modules, written and contributed by open source Puppet and Puppet Enterprise users.
@@ -44,18 +45,19 @@ To publish your module:
44
45
*[Installing modules][installing]: How to install pre-built modules from the Puppet Forge.
45
46
*[Using plugins][plugins]: How to arrange plugins (such as custom facts and custom resource types) in modules and sync them to agent nodes.
46
47
*[Documenting modules][documentation]: How to write good documentation for your modules.
47
-
*[Puppet Development Kit][pdk]: A package of development and testing tools to help you create great modules.
48
+
*[Vox Pupuli Development Kit][devkit]: A package of development and testing tools to help you create great modules.
48
49
49
50
50
-
## Naming your module
51
+
## Naming your module
51
52
52
53
Your module has two names: a short name, like "mysql", and a long name that includes your Forge username, like "puppetlabs-mysql".
53
54
54
55
To upload to the Forge, use the module long name. This name is composed of your Forge username and the short name of your module. For example, the "puppetlabs" user maintains a "mysql" module, which is known to the Forge as "puppetlabs-mysql". Use this long name in your module's `metadata.json` file. This helps disambiguate modules that might have common short names, such as "mysql" or "apache."
55
56
56
57
However, your module directory on disk must use the short name, without the username prefix. Module directory names cannot contain dashes or periods; only letters, numbers, and underscores. As long as you have the correct long name in your `metadata.json` file, the `puppet module build` command uses the correct names in the correct places.
57
58
58
-
> **Note**: Although the Forge expects to receive modules named `username-module`, its web interface presents them as `username/module`. Always use the `username-module` style in your metadata files and when issuing commands.
59
+
{% include alert.html type="note" content="Although the Forge expects to receive modules named `username-module`, its web interface presents them as `username/module`. Always use the `username-module` style in your metadata files and when issuing commands." %}
60
+
59
61
60
62
Related topics:
61
63
@@ -77,13 +79,18 @@ Before you build your module package for publishing, you'll need to make sure it
77
79
78
80
To do this, you'll exclude unnecessary files from your package or repository, remove or ignore any symlinks your module contains, and make sure your `metadata.json` contains the correct information.
79
81
80
-
>**Note:** In order to successfully publish your module to the Puppet Forge and ensure that everything is rendered correctly, your README, license file, changelog, and metadata.json must be UTF-8 encoded. If you used the Puppet Development Kit (or the deprecated `puppet module generate` command) to create your module, these files are already UTF-8 encoded.
82
+
{% include alert.html type="note" content="In order to successfully publish your module to the Puppet Forge and ensure that everything is rendered correctly, your `README`, license file, changelog, and `metadata.json` must be UTF-8 encoded. If you used modern tooling to create your module, these files are already UTF-8 encoded." %}
83
+
81
84
82
85
### Excluding files from the package
83
86
84
-
To exclude certain files from your module build, include them in either a `.gitignore` or a `.pmtignore` file. This is useful for excluding files that are not needed to run the module, such as files generated by spec tests. The ignore file must be in the root directory.
87
+
It can be useful to exclude files that are not needed to run the module, such as files generated by spec tests.
88
+
This can reduce the size of your generated module or reduce user clutter, for example.
89
+
To exclude files, add them to an [ignore file][ignore] in the root directory.
90
+
Files in `.pdkignore` will be excluded from module builds.
91
+
Files in `.gitignore` will be excluded from modules and also from git, unless specifically added.
85
92
86
-
#### .pmtignore example
93
+
#### `.pdkignore` example
87
94
88
95
```
89
96
import/
@@ -101,52 +108,47 @@ junit/
101
108
tmp/
102
109
```
103
110
104
-
The `.pmtignore` file excludes files during `puppet module build` only. For example, you might want spec tests in your source control but not in your module package, so you would list them in `.pmtignore`. To prevent files, such as those in temporary directories, from ever being checked into Git, use `.gitignore`.
111
+
The `.pdkignore` file excludes files during `jig module build` only. For example, you might want spec tests in your source control but not in your module package, so you would list them in `.pdkignore`. To prevent files, such as those in temporary directories, from ever being checked into Git, use `.gitignore`.
105
112
106
-
If you have both a `.pmtignore` and a `.gitignore` file, the `puppet module` command uses the `.pmtignore` file.
113
+
If you have both a `.pdkignore` and a `.gitignore` file, the `jig module` command uses the `.pdkignore` file.
107
114
108
115
### Removing symlinks from your module
109
116
110
-
Symlinks in modules are unsupported. If your module contains symlinks, either remove them or ignore them before you build your module.
117
+
Symlinks in modules are unsupported.
118
+
If your module contains symlinks, either remove them or ignore them before you build your module.
111
119
112
-
If you try to build a module package that contains symlinks, you will receive the following error:
120
+
{% include alert.html type="warning" content="If you try to build a module package that contains symlinks, you will receive an warning informing you to remove them. They will not be included in the module package." %}
113
121
114
-
```
115
-
Warning: Symlinks in modules are unsupported. Please investigate symlink manifests/foo.pp->manifests/init.pp.
116
-
Error: Found symlinks. Symlinks in modules are not allowed, please remove them.
117
-
Error: Try 'puppet help module build' for usage
118
-
```
119
122
120
123
### Adding module metadata in `metadata.json`
121
124
122
125
To publish your module on the Forge, it must contain required metadata in a `metadata.json` file.
123
126
124
-
If you generated your module using the Puppet Development Kit or the deprecated `puppet module generate` command, you'll already have a `metadata.json` file. Check it and make any necessary edits.
127
+
If you generated your module using modern tooling, you'll already have a `metadata.json` file. Check it and make any necessary edits.
125
128
126
129
If you assembled your module manually, you must make sure that you have a `metadata.json` file in your module's main directory. For details on writing or editing the `metadata.json` file, see the related topic about module metadata.
127
130
128
-
> **Modulefiles**
129
-
>
130
-
> If you maintain older modules, you might find the metadata stored in a Modulefile. Move any metadata contained in the Modulefile to the `metadata.json`. Modulefiles were deprecated in Puppet 3 and removed in Puppet 4. They are now treated like any other text file in the root directory of the module.
131
+
{% include alert.html type="warning" content="If you maintain very old modules, you might find the metadata stored in a `Modulefile`. Move any metadata contained in the `Modulefile` to `metadata.json`. Modulefiles were deprecated in Puppet 3 and removed in Puppet 4. They are now treated like any other text file in the root directory of the module." %}
132
+
131
133
132
134
Related topics:
133
135
134
136
*[Module metadata and `metadata.json`][metadata]
135
137
*[Semantic versioning](http://semver.org/)
136
138
137
139
138
-
## Build your module
140
+
## Build your module
139
141
140
142
To upload your module to the Forge, you first must build the module package.
141
143
142
-
1. From the command line, run `puppet module build <MODULE DIRECTORY>`. This command generates a `.tar.gz` package and saves it in the module's `pkg/` subdirectory.
144
+
1. From the command line in your module's root directory, run `jig build build`. This command generates a `.tar.gz` package and saves it in the module's `pkg/` subdirectory.
0 commit comments