Init API

To keep Monteur setup in your application seamlessly, Monteur has a dedicated Init API just for the job. This section explains how to utilize this Init API and setup your repository in a single go.

Initialize Your Repository

To initialize your repository, go to your repository’s root directory, and simply issue the following command:

1
monteur init

Monteur shall properly scan for its existence and if it is absent, Monteur shall do the rest of the config files creation automatically.

Fill in Your App Metadata

Once all files are created, it’s time to update your application metadata once will do. There are a few critical files to update:

App metadata.toml

The main metadata TOML configuration file is located in .configs/monteur/app/config/en/metadata.toml. This file houses all the core metadata of your application that will be used across many packagers and releasers system.

Among the information you need to update when appropriate are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
[Software]
Name = '<directory Name in title case>'
Command = '<directory name in filepath format>'
ID = '<directory name in filepath format>'
Version = 'v0.0.1' # version number
Category = 'devel' # software category
Suite = ''         # software suite (e.g. MSFT Office for MSFT Word)
Abstract = 'software XYZ tool in one single app.'
Description = """
Describe your software as much as you want. Please make sure you end it with
its unique selling pitch.
"""
Website = 'https://example.com/'

[Software.Contact]
Name = 'ACME Entity'
Email = [ '[email protected]' ]




[Software.Maintainers.ACME]
Name = 'ACME Entity'
Email = [ '[email protected]' ]
[Software.Maintainers.ACME.JointTime]
Year = '2021'




[Software.Contributors.ACME]
Name = 'ACME Entity'
Email = [ '[email protected]' ]
[Software.Contributors.ACME.JointTime]
Year = '2021'




[Software.Sponsors.ACME]
Name = 'ACME Entity'
Email = [ '[email protected]' ]
[Software.Sponsors.ACME.JointTime]
Year = '2021'

App help.toml

Although not required, you should look into the help.toml which contains all the general help guides for various help documentations like man pages and etc. The default is good enough to automate most of the known documentations. If you are not using it, you can leave it as it is.

The file is located in .configs/monteur/app/config/en/help.toml. It has the following template that will be automatically formatted based on your app metadata.toml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
[Help]
Command = '$ {{ .App.Command }} help'
Description = '{{ .App.Abstract }}'
Resources = 'Visit {{ .App.Website }} for detailed documentations.'

[Help.Manpage]
Lv1 = """
.\\" {{ .App.Name }} - Lv1 Manpage
.\\" Contact {{ index .App.Contact.Email 0 }} for errors or typos.
.TH man 1 "{{- .App.Time.Day }} {{ .App.Time.Month }} {{ .App.Time.Year -}}" "{{- .App.Version -}}" "{{- .App.ID }} man page"

.SH NAME
{{ .App.Name }} - {{ .App.Abstract }}

.SH SYNOPSIS
{{ .App.Help.Command }}

.SH DESCRIPTION
{{ .App.Description -}}

.SH OPTIONS
{{ .App.Help.Description }}

.SH SEE ALSO
{{ .App.Help.Resources }}

#.SH AUTHORS
#{{ range $index, $owner := .App.Maintainers -}}
#       {{- $owner.Name }} ({{- index $owner.Email 0 -}})
#{{ end -}}
"""

App debian.toml

These are Debian’s .deb specific app metadata for packaging your app to the Debian-based operating system. You may need to refer Debian Policy Specification for the fields' descriptions.

The configuration file is located in .configs/monteur/app/config/en/debian.toml and it is currently providing the following template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
[DEB]
Compat = 11
Rules = """
#!/usr/bin/make -f

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
	dh [email protected]

override_dh_auto_build:
	echo "nothing to override"
"""

[DEB.Control]
Essential = false
PackageType = 'deb'
Priority = 'optional'
RulesRequiresRoot = 'binary-targets'
Standards = '4.6.0'
Section = 'devel'

[DEB.Relationships]
'Build-Depends' = [
	'debhelper (>= 11)',
]
'Depends' = [
]

# More Info:
#  https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-vcs-fields
[DEB.VCS]
Type = 'Vcs-Git'
URL = 'https://example.com/git'
Branch = 'main'
#Path = '.'

[DEB.Testsuite]
Paths = [
	# 'relative/path/to/debTestScript',
]

[DEB.Copyright]
Format = 'https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/'
Disclaimer = ''
Comment = ''

[DEB.Changelog]
Urgency = 'low'

[DEB.Source]
Format = '3.0 (native)'
LocalOptions = """
"""
Options = """
"""
LintianOverrides = """
# supply the license file in case OS did not supply one

# we are go package so it is okay not to specify Depends:
"""

[DEB.Install]

Depending on which packager you’re using (e.g. debuild), certain information are compulsory. Monteur itself is using this packager most of the settings are up-to-date.

Among the attention needed from you are:

Lastly, you should update your app copyright’s license metadata. This file holds a license’s full metadata for generating various data files across the repository. A default license TOML file was generated in .configs/monteur/app/config/en/copyrights/copyrights.toml. Please rename it to the appropriate license filename like apache-2.toml for Apache 2.0 license.

Since app can be mutli-licensed (e.g. Creative Commons for non-coding materials and Code Licensing), you can create as many <license>.toml file as you deemed appropriate.

The default TOML license file has the following template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
[Copyright]
Name = 'License Name' # license full name
ID = 'license-name'   # identifiable license ID
Comment = ''
Materials = [ '*' ]
Holders = [
        # A string with year, then name, then email with diamond braces. Ex.:
        #
        #   '2021 John S. Smith <[email protected]>',
        #
        # If the list is empty, all maintainers, contributors, and sponsors
        # shall be attached to it.
]
Notice = """
License notice usually prepend in front of source codes.
"""
Text = """
Full license text body.
"""

Build Your Repository’s CI Jobs

Now that you have your app metadata setup, it’s time to setup your Monteur CI Jobs recipes. Different CI Jobs has different recipe files but they are following the same filesystem which are housing under .configs/monteur/${ci-job}/jobs/ directory.

Each recipe has its own configurations so please go through them accordingly. The initialization shall be completed once you had fully configured all the recipes to your app building.

To start, please head over to:

CI Jobs Catalog

Epilogue

That’s all for Monteur’s Init API. If you have any queries, please proceed to contact us via our Issues Section channel.