-
Notifications
You must be signed in to change notification settings - Fork 5
Expand file tree
/
Copy pathMakeDeb.html
More file actions
438 lines (403 loc) · 21.3 KB
/
MakeDeb.html
File metadata and controls
438 lines (403 loc) · 21.3 KB
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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>MakeDeb documentation</title>
<style type="text/css">
html
{
font-family: sans-serif;
line-height: 130%;
}
pre, code
{
font-size: 0.9rem;
}
.comment
{
color: #808080;
}
.keyword
{
color: #0000e0;
}
.variable
{
color: #c000c0;
}
</style>
</head>
<body>
<h1>MakeDeb documentation</h1>
<p>
<a href="https://github.com/ygoe/DotnetMakeDeb"><strong>MakeDeb</strong></a> creates a .deb Debian binary package from local files, instructed by a text specification file. It is a console application that takes its commands from command line parameters. You need .NET 6.0 (Windows, Linux) or the .NET Framework 4.8 (Windows) to run this tool. MakeDeb is truly portable, there are no other dependencies or additional libraries required.
</p>
<h2 id="toc">Contents</h2>
<ul>
<li><a href="#toc">Contents</a></li>
<li><a href="#commandline">Command line</a></li>
<li><a href="#specfile">Specification file</a>
<ul>
<li><a href="#directives">Directives</a>
<ul>
<li><a href="#dir_basepath">basepath</a></li>
<li><a href="#dir_outdir">outdir</a></li>
<li><a href="#dir_package">package</a></li>
<li><a href="#dir_version">version</a></li>
<li><a href="#dir_convert-semver">convert-semver</a></li>
<li><a href="#dir_section">section</a></li>
<li><a href="#dir_priority">priority, prio</a></li>
<li><a href="#dir_architecture">architecture, arch</a></li>
<li><a href="#dir_depends">depends</a></li>
<li><a href="#dir_pre-depends">pre-depends</a></li>
<li><a href="#dir_conflicts">conflicts</a></li>
<li><a href="#dir_maintainer">maintainer</a></li>
<li><a href="#dir_homepage">homepage</a></li>
<li><a href="#dir_description">description, desc</a></li>
<li><a href="#dir_preinst">preinst</a></li>
<li><a href="#dir_postinst">postinst</a></li>
<li><a href="#dir_prerm">prerm</a></li>
<li><a href="#dir_postrm">postrm</a></li>
<li><a href="#dir_file">file</a></li>
<li><a href="#dir_conffile">conffile</a></li>
<li><a href="#dir_directory">directory, dir</a></li>
</ul></li>
<li><a href="#variables">Variables</a></li>
<li><a href="#example">Example file</a></li>
</ul></li>
</ul>
<h2 id="commandline">Command line</h2>
<p>
MakeDeb accepts a number of command line parameters:
</p>
<ol>
<li>The package specification file (mandatory)</li>
<li>The override package version (optional)</li>
</ol>
<p>
The specification file name can be a relative path which is interpreted relative to the current working directory.
File names within the specification file will be interpreted relative to the file itself.
The file format is explained below.
The output file name is derived from the package name, version, and architecture.
The output directory can be controlled with the <code><a href="#dir_outdir">outdir</a></code> directive.
</p>
<p>
The specification must define a <a href="#dir_version">version</a> number for the packaged software.
However, you can override this version from more current data from an automated build process.
This value from the command line entirely replaces whatever is defined in the spec file.
</p>
<p>
Example invocation:
</p>
<pre>
make-deb %SolutionDir%\Setup\app.debspec 1.2.0
</pre>
<p>
The package version can also be looked up from another file, like the built application assembly.
Use the <code>-vf</code> option to specify the file to read the version from:
</p>
<pre>
make-deb %SolutionDir%\Setup\app.debspec -vf %ProjectDir%\bin\Release\netcoreapp3.0\linux-x64\publish\MyApp.dll
</pre>
<p>
The version file lookup overrides the command line value, which overrides the version set in specification file.
</p>
<h2 id="specfile">Specification file</h2>
<p>
The specification file is a plain text file.
Each line contains one directive.
Empty lines are ignored.
Lines starting with a hash (#), possibly with leading whitespace, are comments and also ignored.
There are two types of lines: <a href="#directives">directives</a> and <a href="#variables">variables</a>.
A <a href="#example">complete example file</a> is available further down.
</p>
<p>
Most of the directives in the specification file just set the corresponding entry in the Debian package control file.
Please read the <a href="https://www.debian.org/doc/debian-policy/">Debian Policy Manual</a> to understand the policy requirements for the Debian distribution.
</p>
<h3 id="directives">Directives</h3>
<p>
A directive line follows the general format:
The name of the directive (case-insensitive), followed by a colon (:), followed by the value for the directive.
White-space around the colon is ignored.
Options without a value do not have a colon either. Examples:
</p>
<pre>
package: myapp
version: 1.0
depends: libxml, libz
convert-semver
</pre>
<p>
The following directives are available:
</p>
<h4 id="dir_basepath">basepath</h4>
<p>
Sets the base path for all source files referenced in the spec file.
This should usually point from the specification file directory up to your software solution’s root directory.
If unset, the spec file’s directory is used as base path.
Non-rooted paths are interpreted relative to the specification file.
</p>
<h4 id="dir_outdir">outdir</h4>
<p>
Sets the output directory for the generated .deb package file.
If unset, the current working directory is used.
Non-rooted paths are interpreted relative to the specification file.
</p>
<h4 id="dir_package">package</h4>
<p>
Sets the name of the package.
This is a mandatory directive.
Only the following characters are allowed for package names: lower-case letters (a-z), digits (0-9), plus (+), point (.), hyphen (-).
See the <a href="https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-package">Debian Policy Manual</a> for details on this field.
</p>
<h4 id="dir_version">version</h4>
<p>
Sets the version of the package.
The version can be composed of the original software version and a package version.
This is a mandatory directive.
Only the following characters are allowed for version numbers: upper-case letters (A-Z), lower-case letters (a-z), digits (0-9), plus (+), point (.), hyphen (-), tilde (~).
See the <a href="https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-version">Debian Policy Manual</a> for details on this field.
</p>
<h4 id="dir_convert-semver">convert-semver</h4>
<p>
If set, converts the specified or overridden version from SemVer to Debian conventions.
The hyphen (-) has a different meaning in both systems.
In SemVer it denotes a prerelease, in Debian it has no such special meaning.
The conversion is represented with the following regular expression substitution:
</p>
<pre>
s/^([0-9]+\.[0-9]+\.[0-9]+)-([^-]+)[^.+]*(\.[0-9]+)?(\+[^-]+)?/$1~$2$3$4/
</pre>
<h4 id="dir_section">section</h4>
<p>
Sets the section of the package.
See the <a href="https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-section">Debian Policy Manual</a> for details on this field.
</p>
<h4 id="dir_priority">priority, prio</h4>
<p>
Sets the priority of the package.
See the <a href="https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-priority">Debian Policy Manual</a> for details on this field.
</p>
<h4 id="dir_architecture">architecture, arch</h4>
<p>
Sets the hardware architecture of the package.
The special value “all” indicates that the package can be installed on all architectures.
This is a mandatory directive.
See the <a href="https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-architecture">Debian Policy Manual</a> for details on this field.
</p>
<p>
Common values are: all, i386, amd64, armhf, arm64
</p>
<h4 id="dir_depends">depends</h4>
<p>
Sets the packages that this package depends on to be installed.
This directive can be used multiple times to split many dependencies over multiple lines in the spec file.
See the <a href="https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps">Debian Policy Manual</a> for details on this field.
</p>
<h4 id="dir_pre-depends">pre-depends</h4>
<p>
Sets the packages that this package depends on to be installed.
This directive can be used multiple times to split many dependencies over multiple lines in the spec file.
See the <a href="https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps">Debian Policy Manual</a> for details on this field, and how it differs from <a href="#dir_depends">depends</a>.
</p>
<h4 id="dir_conflicts">conflicts</h4>
<p>
Sets the packages that this package conflicts with.
See the <a href="https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps">Debian Policy Manual</a> for details on this field.
</p>
<h4 id="dir_maintainer">maintainer</h4>
<p>
Sets the name and e-mail address of the maintainer of the package.
This is a mandatory directive.
See the <a href="https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-maintainer">Debian Policy Manual</a> for details on this field.
The format is: <code>Full Name <email@example.com></code>
</p>
<h4 id="dir_homepage">homepage</h4>
<p>
Sets the URL of the website that contains additional information on the package and possibly allows downloading of the package file.
See the <a href="https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-homepage">Debian Policy Manual</a> for details on this field.
</p>
<h4 id="dir_description">description, desc</h4>
<p>
Sets the description of the package.
This consists of multiple lines.
The first line (on the same line as the directive name) contains the single-line synopsis that is displayed in package listings.
The additional lines contain the multi-line description in more detail.
Each of the subsequent lines must start with a single space character.
Otherwise empty lines must contain a single point (.) after the leading space.
This is a mandatory directive. See the <a href="https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-description">Debian Policy Manual</a> for details on this field.
</p>
<h4 id="dir_preinst">preinst</h4>
<p>
Sets the name of the pre-installation script file.
This file is included in the control part of the package and may be called during installation or other operations of the package.
It will not be available on the target system after installation.
See the <a href="https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html">Debian Policy Manual</a> for details on this file.
Non-rooted paths are interpreted relative to the <a href="#dir_basepath">base path</a>, if set before this directive.
</p>
<p>
The file name must not contain spaces.
To convert the file from DOS to Unix line endings, add the keyword <code>text</code> after the file name, spearated by a space.
</p>
<h4 id="dir_postinst">postinst</h4>
<p>
Sets the name of the post-installation script file.
This file is included in the control part of the package and may be called during installation or other operations of the package.
It will not be available on the target system after installation.
See the <a href="https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html">Debian Policy Manual</a> for details on this file.
Non-rooted paths are interpreted relative to the <a href="#dir_basepath">base path</a>, if set before this directive.
</p>
<p>
The file name must not contain spaces.
To convert the file from DOS to Unix line endings, add the keyword <code>text</code> after the file name, spearated by a space.
</p>
<h4 id="dir_prerm">prerm</h4>
<p>
Sets the name of the pre-remove script file.
This file is included in the control part of the package and may be called during uninstallation or other operations of the package.
It will not be available on the target system after installation.
See the <a href="https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html">Debian Policy Manual</a> for details on this file.
Non-rooted paths are interpreted relative to the <a href="#dir_basepath">base path</a>, if set before this directive.
</p>
<p>
The file name must not contain spaces.
To convert the file from DOS to Unix line endings, add the keyword <code>text</code> after the file name, spearated by a space.
</p>
<h4 id="dir_postrm">postrm</h4>
<p>
Sets the name of the post-remove script file.
This file is included in the control part of the package and may be called during uninstallation or other operations of the package.
It will not be available on the target system after installation.
See the <a href="https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html">Debian Policy Manual</a> for details on this file.
Non-rooted paths are interpreted relative to the <a href="#dir_basepath">base path</a>, if set before this directive.
</p>
<p>
The file name must not contain spaces.
To convert the file from DOS to Unix line endings, add the keyword <code>text</code> after the file name, spearated by a space.
</p>
<h4 id="dir_file">file</h4>
<p>
Adds a local file to the data part of the package.
This file will be unpacked to the target system when the package is installed.
This directive has multiple parameters that are separated by white-space (any number of spaces or tabs):
</p>
<ul>
<li>The source path: The file is read from this path. Non-rooted paths are interpreted relative to the <a href="#dir_basepath">base path</a>, if set before this directive.</li>
<li>The destination path: The file is unpacked to this path on the target system. Target paths are always relative to the root directory (/) but do not include the leading slash. If it ends with a slash (/), it is interpreted as a directory name and the source file name will be appended to it.</li>
<li>Optional: <code>text</code> keyword to convert the file from DOS to Unix line endings.</li>
<li>The file mode: The target file is created with the specified mode, written in the usual octal notation. If unset, the default file mode is 644 (owner-write, world-read, no execute).</li>
<li>The file user ID: The target file is owned by the user with the specified numeric user ID. If unset, the file will be owned by the root user (ID 0).</li>
<li>The file group ID: The target file is owned by the group with the specified numeric group ID. If unset, the file will be owned by the root group (ID 0).</li>
</ul>
<p>
The source path may contain wildcards (* and ?) in the file name (not in the directory).
If such a wildcard occurs, a file item for each local found file is added in place of this directive.
Wildcards can only be used with a destination path that only specifies the directory, not a file name, i.e. that ends with a slash (/).
The destination file name will be used from the local file that matches the wildcard.
All other parameters (mode, owner, group) are applied equally to all found files.
</p>
<p>
If the last path segment (the file name) of the source path is <code>**</code> then all files from the specified directory and all its subdirectories are included.
The destination file name includes the subdirectory path relative to the specified directory.
This allows the inclusion of entire subtrees of directories and files.
</p>
<p>
Source files can be specified multiple times.
The last entry will overwrite any previous entry.
This can be used to set different modes or owners for specific files that were already covered by a wildcard.
In this case, the wildcard entry must occur before the specific file entry.
</p>
<h4 id="dir_conffile">conffile</h4>
<p>
Adds a local file as configuration file to the data part of the package.
This behaves exactly like the <code><a href="#dir_file">file</a></code> directive.
The installed file is known to the package as a configuration file so it can handle changes to this file when upgrading the package.
</p>
<p>
Configuration source file entries can also overwrite normal file entries by the same source path.
This may also be used to add many files by a wildcard and mark one of them as configuration file separately.
</p>
<h4 id="dir_directory">directory, dir</h4>
<p>
Adds an empty directory to the data part of the package.
Normally you do not need to explicitly add directories for files, MakeDeb handles that for you.
This directive can be used to explicitly create directories with certain modes or owners, and it must be used to create empty directories on the target system.
This directive has multiple parameters that are separated by white-space (any number of spaces or tabs):
</p>
<ul>
<li>The destination path: The path of the directory created on the target system. Target paths are always relative to the root directory (/) but do not include the leading slash. Directory paths do not include a trailing slash; if one is set, it will be removed silently.</li>
<li>The directory mode: The target directory is created with the specified mode, written in the usual octal notation. If unset, the default directory mode is 755 (owner-write, world-read).</li>
<li>The directory user ID: The target directory is owned by the user with the specified numeric user ID. If unset, the directory will be owned by the root user (ID 0).</li>
<li>The directory group ID: The target directory is owned by the group with the specified numeric group ID. If unset, the directory will be owned by the root group (ID 0).</li>
</ul>
<p>
Note: These parameters are similar to the <code>file</code> directive, only the first value (local source) is left out.
</p>
<p>
The order in which files and directories are mentioned in the spec file does not matter (except for wildcard files, see above).
MakeDeb will first create all explicitly specified directories and then add the files (along with their implicit directories unless already created).
</p>
<h3 id="variables">Variables</h3>
<p>
Variables can be defined in the specification file to define common values only once.
Variables must be defined before they are used.
They can be changed anywhere in the file, affecting usage after the new assignment.
A variable line follows the general format:
The name of the variable (case-sensitive), followed by an equals sign (=), followed by the value for the variable.
White-space around the equals sign is ignored.
Examples:
</p>
<pre>
ETCDIR = etc/myapp
BINDIR = usr/local/bin
</pre>
<p>
The usage of such variables is by putting the variable name (case-sensitive) within curly braces. Example:
</p>
<pre>
file: MyApp\bin\Release\MyApp.exe {BINDIR}/myapp 755
</pre>
<h3 id="example">Example file</h3>
<p>
The following example assumes a Visual Studio solution directory that contains the project directories “MyApp” and “MyLib”, and an additional directory “Setup” that contains all setup-related files.
The specification file is stored in the “Setup” directory.
</p>
<pre>
<span class="comment"># Spec file options</span>
<span class="keyword">basepath</span>: ..
<span class="keyword">outdir</span>: bin
<span class="comment"># Common directory variables</span>
<span class="variable">ETCDIR</span> = etc/myapp
<span class="variable">OPTDIR</span> = opt/myapp
<span class="comment"># Package control file</span>
<span class="keyword">package</span>: myapp
<span class="keyword">version</span>: 1.2
<span class="keyword">architecture</span>: all
<span class="keyword">depends</span>: mono-runtime, libmono-system-runtime4.0-cil, libmono-system4.0-cil
<span class="keyword">depends</span>: libmono-sqlite4.0-cil, libmono-system-data4.0-cil
<span class="keyword">maintainer</span>: Example Developer <developer@example.com>
<span class="keyword">homepage</span>: https://example.com/myapp
<span class="keyword">description</span>: My application
My application can do truly miraculous things, read the user's mind and works
perfectly in every aspect.
.
If you ever wanted your computer to understand you and be helpful, then this
little tool is all you need.
<span class="comment"># Maintenance scripts</span>
<span class="keyword">preinst</span>: Setup\Linux\preinst <span class="keyword">text</span>
<span class="keyword">postinst</span>: Setup\Linux\postinst <span class="keyword">text</span>
<span class="keyword">prerm</span>: Setup\Linux\prerm <span class="keyword">text</span>
<span class="keyword">postrm</span>: Setup\Linux\postrm <span class="keyword">text</span>
<span class="comment"># Startup scripts and configuration</span>
<span class="keyword">file</span>: Setup\Linux\myapp etc/init.d/ 755
<span class="keyword">conffile</span>: Setup\Config\Linux\myapp.cfg <span class="variable">{ETCDIR}</span>/ <span class="keyword">text</span>
<span class="comment"># Application files</span>
<span class="keyword">file</span>: MyApp\bin\Release\MyApp.exe <span class="variable">{OPTDIR}</span>/ 755
<span class="keyword">file</span>: MyApp\bin\Release\MyApp.exe.config <span class="variable">{OPTDIR}</span>/
<span class="keyword">file</span>: MyLib\bin\Release\MyLib.dll <span class="variable">{OPTDIR}</span>/
<span class="comment"># Create log directory</span>
<span class="keyword">dir</span>: var/log/myapp
</pre>
</body>
</html>