Creating a package

This guide walks you through the creation of your first bring package. For details about the package description format, available package types and other more in-depth in formation check out the package description documentation.

Create the package description file¶

For this example, we'll create a package for one of the files in this example git repository, specifically this file.

Since the file we are interested in is hosted on Gitlab, and we only are interested in this particular file and not the whole repository, we will use the gitlab_files package type.

...using the `create pkg-desc` sub-command¶

bring package types come with some helpers to make it easier to create package descriptions by auto-filling in some required and/or default values.

Without any arguments (apart from the required package type name), bring create pkg-desc [package-type] will return a bare package description string, which you can use as a starting point by copying it into a file and filling in some required values:


> bring create pkg-desc gitlab_files

---
# info:
#   slug: <package_description>
#   homepage: 'https://example.com'

# tags:
#  - <tag1>
#  - <tag2>

# labels:
#   <key>: <value>
#   # e.g.:
#   language: <language>


source:

  type: gitlab_files


  user_name: <string_value>        # required
  repo_name: <string_value>        # required
  files: <string_value>        # required
  # tag_filter: <string_value>        # optional
  # template_values: <dict_value>        # optional

#  aliases:
#    <var_name>:
#      <alias>: <actual_value>
#      <alias_2>: <actual_value_2>
#    # e.g.:
#    arch:
#      x86_64: x86-64

#  artefact:
#    # possible values: file, folder, archive
#    type: archive

#  transform:
#    # filter by path of the original source file
#    - <orig_file>
#    # or, filter original source file, but rename/move
#    - <orig_file>: <target_path>
#    # or, filter original source file, but rename/move and/or change file mode
#    - from: <orig_file>
#      path: <target_path>
#      mode: '0755'

We can also tell bring to create the package description file straight away:


> bring create pkg-desc gitlab_files -f example-file1

Saved package descrition to: /builds/frkl/bring/example-file1.pkg.br

Note: if no file extension is provided, bring will use the default '.pkg.br'

We can now go through that file, and fill in the 3 required values for the gitlab_files package type:

user_name: in our case bring-indexes
repo_name: here we use example-source-repo
files: we only want one file, so we use a single-item list: ['some-files/file1.md']

Once that is done, we can use the explain sub-command to get the details of our newly create package:


> bring explain package example_file1.pkg.br

Package example_file1.pkg.br

 Variables

 version   The version of the package.
        
           default    latest                 
           required   yes                    
           type       string                 
           allowed    v1.1.0 (alias: latest) 
                      v1.0.0                 
                      master                 
                      develop

As you can see in that output, bring determined the available versions, and selected an appropriate alias for the latest tag.

We could now comment out some of the metadata fields and fill in some of the values manually. Or we could be...

...using the `create pkg-desc` command with arguments¶

Some package type plugins support auto-filling some of the metadata (and other) values of a package description, given enough basic information.

For the gitlab_files plugin we can find out which values are required by issuing:

> bring create pkg-desc gitlab_files --help
Usage: bring create pkg-desc gitlab_files [OPTIONS] [PKG_NAME_OR_PATH]

Options:
  --files FILES                   The list of files to retrieve.
  --repo-name REPO_NAME           The gitlab repo path (not internal name,
                                  which is different in some cases).
  --tag-filter TAG_FILTER         if provided, is used as regex to select
                                  wanted tags
  --template-values TEMPLATE_VALUES
                                  An (optional) map with the possible template
                                  var names in the value for 'files' as keys,
                                  and all allowed values for each key as
                                  value.
  --user-name USER_NAME           The gitlab user name.
  -f, --force                     overwrite existing package description
  -h, --help                      Show this message and exit.

Let's try that:


> bring create pkg-desc gitlab_files --user-name bring-indexes --repo-name example-source-repo --files some-file/file1.md

---
info:
  slug: Example files to turn into bring packages.
  homepage: https://gitlab.com/bring-indexes/example-source-repo


# tags:
#  - <tag1>
#  - <tag2>

# labels:
#   <key>: <value>
#   # e.g.:
#   language: <language>


source:

  type: gitlab_files

  user_name: bring-indexes
  repo_name: example-source-repo
  files:
  - some-file/file1.md

  # tag_filter: <string_value>        # optional
  # template_values: <dict_value>        # optional

#  aliases:
#    <var_name>:
#      <alias>: <actual_value>
#      <alias_2>: <actual_value_2>
#    # e.g.:
#    arch:
#      x86_64: x86-64

#  artefact:
#    # possible values: file, folder, archive
#    type: archive

#  transform:
#    # filter by path of the original source file
#    - <orig_file>
#    # or, filter original source file, but rename/move
#    - <orig_file>: <target_path>
#    # or, filter original source file, but rename/move and/or change file mode
#    - from: <orig_file>
#      path: <target_path>
#      mode: '0755'

As with the example above, we can use a file-path argument at the end of this command to write this description to a file straight away. This description should be usable without any further manual editing, since we provided all required values via the command-line. Plus, bring added some of the metadata in 'info' automatically (which we could change, if we don't like it).

Creating a package

Create the package description file¶

...using the create pkg-desc sub-command¶

...using the create pkg-desc command with arguments¶

...using the `create pkg-desc` sub-command¶

...using the `create pkg-desc` command with arguments¶