/
readme.html
554 lines (368 loc) · 29.4 KB
/
readme.html
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
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Simple Build Agent (in Perl)</title>
<link rel="stylesheet" href="etc/podstyle.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<ul id="index">
<li><a href="#Simple-Build-Agent-in-Perl">Simple Build Agent (in Perl)</a>
<ul>
<li><a href="#Description">Description</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#Options">Options</a>
<ul>
<li><a href="#Notification-Options">Notification Options</a></li>
</ul>
</li>
<li><a href="#Instructions">Instructions</a>
<ul>
<li><a href="#Configuration-File-Details">Configuration File Details</a>
<ul>
<li><a href="#Example-config-file">Example config file:</a></li>
<li><a href="#Structure-of-a-configuration-file">Structure of a configuration file:</a></li>
<li><a href="#Per-build-Config-parameters">Per-build Config parameters:</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#Built-in-Utilities-for-Scripted-Builds">Built-in Utilities for Scripted Builds</a>
<ul>
<li><a href="#FTP-Distribution">FTP Distribution</a></li>
<li><a href="#Zip-Archive-Utility">Zip Archive Utility</a></li>
<li><a href="#Embedding-system-commands">Embedding system commands</a></li>
</ul>
</li>
<li><a href="#E-Mail-Notifications">E-Mail Notifications</a></li>
<li><a href="#Requires">Requires</a></li>
<li><a href="#Author">Author</a></li>
<li><a href="#Copyright-License-and-Disclaimer">Copyright, License, and Disclaimer</a></li>
</ul>
</li>
</ul>
<h1 id="Simple-Build-Agent-in-Perl">Simple Build Agent (in Perl)</h1>
<h2 id="Description">Description</h2>
<p><i>SBA</i> is designed as a very basic "build server" (or <a href="http://en.wikipedia.org/wiki/Continuous_integration">CI</a>, if you prefer). It can compare a local and remote code repo (SVN for now), and if changes are detected then it can pull the new version and launch build step(s) (eg. to build different versions of the same code, distribute builds to multiple places, or whatever). It's basically a replacement for using batch/shell scripts to manage code updates/builds/distribution, with some built-in features geared specifically for such jobs.</p>
<p>All configuration is done via simple INI files. Each configuration can run multiple builds, and each build can run up to 5 steps, for example: <i>clean</i>, <i>build</i>, <i>deploy</i>, <i>distribute</i>, and <i>finish</i>. It can also be forced to launch builds, regardless of repo status.</p>
<p>Each step can run any system command, for example <code><code>make</code></code>, along with any required arguments. If you can run it from the command line, then it should work when run via <i>SBA</i>. All steps are optional.</p>
<p>A built-in simple <a href="#Zip-Archive-Utility">"Zip Archive Utility"</a> is included for quick packaging of build results before distribution.</p>
<p>For distribution of build results ("artifacts"), a built-in <a href="#FTP-Distribution">FTP client</a> can be used to upload files to a server.</p>
<p>Finally, a notification e-mail can be sent to multiple recipients, including a full log of the job results.</p>
<p>Limitations/TODO:</p>
<dl>
<dt id="Only-checks-the-currently-checked-out-branch-of-a-repo-for-updates.-Does-not-detect-new-branches-tags-etc">Only checks the currently checked-out branch of a repo for updates. Does not detect new branches/tags/etc.</dt>
<dd>
</dd>
<dt id="Add-Git-support">Add Git support.</dt>
<dd>
</dd>
</dl>
<p>WARNING: The whole point of this program is to execute system commands (scripts) contained in a configuration file. As such, you need to take great care if running configuration files from untrusted sources (like a public code repo). In fact you shouldn't do it, ever!</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p>See full <a href="#INSTRUCTIONS">"INSTRUCTIONS"</a> below (run <code><code>sba --man</code></code> if needed).</p>
<pre><code><code> - Create a config file, eg. mybuilds.ini.
- Put it in the same folder as you would normally launch builds from.
- Run: sba.pl -c path/to/mybuilds.ini
Summary:
sba.pl -c <config file> [other options]
</code></code></pre>
<h2 id="Options">Options</h2>
<p>Note: all options can appear in the configuration file's [settings] block using the same names (long versions) as shown here, minus the "--" part. See <a href="#INSTRUCTIONS">"INSTRUCTIONS"</a> below for details about config file format.</p>
<dl>
<dt id="c-file-default:-.-sba.ini"><b>-c</b> <file> <i>(default: ./sba.ini)</i></dt>
<dd>
<p>Configuration file to use. The path of this file also determines the default working directory, unless <code><code>--work-folder</code></code> is also specified.</p>
</dd>
<dt id="work-folder-or--w-path-default:-path-of-config-file"><b>--work-folder</b> or <b>-w</b> [<path>] <i>(default: path of config file)</i></dt>
<dd>
<p>Set working directory specifically. The working directory determines the base path for all executed commands (all paths are relative to this).</p>
</dd>
<dt id="log-folder-or--l-path-default:-work-folder-log"><b>--log-folder</b> or <b>-l</b> [<path>] <i>(default: {work-folder}/log)</i></dt>
<dd>
<p>Path for all output logs. <i>SBA</i> generates its own log (same as what you'd see on the console), plus the output of every command is directed to its own log file (eg. log/build1-clean.log, log/build1-build.log, etc). Absolute path, or relative to working directory. You might want to set it to be inside the build directory, as in the provided examples. Default is <i>log</i> folder inside the current working directory.</p>
<p>To disable all logging, set this value to blank (eg. "<code><code>--log-folder</code></code>" or "<code><code>log-folder = </code></code>" in the config file.</p>
</dd>
<dt id="force-build-or---force-or--f-default:-0-false"><b>--force-build</b> or <b>--force</b> or <b>-f</b> <i>(default: 0 (false))</i></dt>
<dd>
<p>Always (re-)build even if no new repo version detected. This can also be specified per build config (see config file details, below).</p>
</dd>
<dt id="quiet-or--q"><b>--quiet</b> or <b>-q</b></dt>
<dd>
<p>Do not print anything to the console (STDOUT/STDERR). Output is still printed to log file (if enabled), and sent in a notification (if enabled).</p>
</dd>
<dt id="debug-or--d"><b>--debug</b> or <b>-d</b></dt>
<dd>
<p>Output extra runtime details.</p>
</dd>
<dt id="help-or--h-or"><b>--help</b> or <b>-h</b> or <b>-?</b></dt>
<dd>
<p>Print usage summary and options.</p>
</dd>
<dt id="man"><b>--man</b></dt>
<dd>
<p>Print full documentation.</p>
</dd>
</dl>
<h3 id="Notification-Options">Notification Options</h3>
<p>(Note: all notify-* option names can also be shortened to just the last part after the dash, eg. <code><code>--to</code></code> and <code><code>--server</code></code>)</p>
<dl>
<dt id="notify-to-e-mail-e-mail-...-required-for-notifcation"><b>--notify-to</b> <e-mail[,e-mail][,...]> <i>(required for notifcation)</i></dt>
<dd>
<p>One or more e-mail addresses separated by commas. Blank to disable notification.</p>
</dd>
<dt id="notify-server-host.name-required-for-notifcation"><b>--notify-server</b> <host.name> <i>(required for notifcation)</i></dt>
<dd>
<p>Server to use for sending mail. Blank to disable notification.</p>
</dd>
<dt id="notify-subj-subject-default:-SBA-Build"><b>--notify-subj</b> <subject> <i>(default: "[SBA] Build")</i></dt>
<dd>
<p>Subject prefix. Status details get appended to this.</p>
</dd>
<dt id="notify-always-default:-0-false"><b>--notify-always</b> <i>(default: 0 (false))</i></dt>
<dd>
<p>Whether to send notifcation even if no builds were performed (eg. no updates were detected, and nothing was forced). Default is 0 (only notify when something was actually done).</p>
</dd>
<dt id="notify-from-sender-e-mail-default:-first-address-in-notify-to"><b>--notify-from</b> <sender e-mail> <i>(default: first address in <code><code>notify-to</code></code>)</i></dt>
<dd>
<p>The sender's e-mail address (also where any bounces would go to). Defaults to the first address found in <code><code>notify-to</code></code> option.</p>
</dd>
<dt id="notify-user-username"><b>--notify-user</b> <username></dt>
<dd>
</dd>
<dt id="notify-pass-password"><b>--notify-pass</b> <password></dt>
<dd>
<p>Specify if your sever needs authentication.</p>
</dd>
<dt id="notify-usetls-default:-0-false"><b>--notify-usetls</b> <i>(default: 0 (false))</i></dt>
<dd>
<p>Use TLS/SSL for server connection. Default is false. Enable if it works with your server.</p>
</dd>
<dt id="notify-port-port-default:-blank"><b>--notify-port</b> <port #> <i>(default: (blank))</i></dt>
<dd>
<p>Optional server port. Default (blank) selects autmatically based on plain/ssl transport.</p>
</dd>
</dl>
<h2 id="Instructions">Instructions</h2>
<p><i>SBA</i> uses a configuration file to determine which tasks to perform. A config file is needed to process any actual build steps you want. The config can provide a set of default actions to perform for each step, and specific actions for individual build(s). In addition, all <i>SBA</i> options can be set in the config file, which is much easier to manage than the command line parameters.</p>
<h3 id="Configuration-File-Details">Configuration File Details</h3>
<h4 id="Example-config-file">Example config file:</h4>
<pre><code><code> -----------------------------------------------------------
[settings]
# these are SBA program settings, same as command-line options.
log-folder = ../build-sba/log
notify-to = me@example.com
notify-server = localhost
notify-subj = "My builds status:"
[build-default]
# default settings for all builds
dir = ../build-sba
clean = make clean clean-bin $common
deploy =
distrib = sba_ftp ftp.myhost.org user pass /nightly $dir/$name/*.hex
# convenience macro to be used in other commands
common = BUILD_TYPE=$name BUILD_PATH=$dir
# all other blocks define individual build configurations
[board-6.0]
build = make all -j1 $common BOARD_VER=6 BOARD_REV=0
[board-6.0-dimu-1.1]
name = board-6.0-dimu
build = make all -j1 $common BOARD_VER=6 BOARD_REV=0 DIMU_VER=1.1
incremental = 1
force = 1
enable = 1
-----------------------------------------------------------</code></code></pre>
<h4 id="Structure-of-a-configuration-file">Structure of a configuration file:</h4>
<dl>
<dt id="Config-file-mostly-follows-standard-.ini-file-format-specifications-with-the-following-caveats">Config file (mostly) follows standard <a href="http://en.wikipedia.org/wiki/INI_file">.ini file format</a> specifications, with the following caveats:</dt>
<dd>
<dl>
<dt id="Parameter-and-variable-names-are-CASE-SENSITIVE">Parameter and variable names are CASE SENSITIVE!</dt>
<dd>
</dd>
<dt id="Comments-can-start-with-a-semicolon-or-hash-mark-or-.-Comments-must-start-on-their-own-line">Comments can start with a semicolon or hash mark (; or #). Comments must start on their own line.</dt>
<dd>
</dd>
<dt id="Long-lines-can-be-split-using-a-backslash-as-the-last-character-of-the-line-to-be-continued-immediately-followed-by-a-newline.-eg">Long lines can be split using a backslash (\) as the last character of the line to be continued, immediately followed by a newline. eg:</dt>
<dd>
<pre><code><code> [Section]
Parameter=this parameter \
spreads across \
a few lines
</code></code></pre>
</dd>
</dl>
</dd>
<dt id="The-optional-settings-block-describes-SBA-runtime-options.-Any-parameter-listed-in-OPTIONS-can-be-used-here-simply-ommit-the-leading----before-the-option-name">The optional <b>[settings]</b> block describes <i>SBA</i> runtime options. Any parameter listed in <a href="#OPTIONS">"OPTIONS"</a> can be used here (simply ommit the leading <code><code>--</code></code> before the option name).</dt>
<dd>
</dd>
<dt id="The-optional-build-default-block-describes-settings-which-are-shared-by-all-build-configs">The optional <b>[build-default]</b> block describes settings which are shared by all build configs.</dt>
<dd>
</dd>
<dt id="Each-subsequent-named-block-describes-a-build-configuration.-Block-names-must-be-unique-and-are-used-as-the-build-name-by-default.-They-are-processed-in-order-of-their-appearance-in-the-.ini-file">Each subsequent <b>[named-block]</b> describes a build configuration. Block names must be unique, and are used as the build name by default. They are processed in order of their appearance in the .ini file.</dt>
<dd>
</dd>
<dt id="Strings-may-contain-embedded-references-macros-to-other-named-params-preceded-with-a-sign.-All-macros-are-evaluated-when-each-config-is-run-vs.-when-the-config-file-is-initially-read-.-Check-the-example-above-to-see-how-the-dir-and-name-variables-are-used-which-correspond-to-the-current-build-directory-and-build-name-respectively">Strings may contain embedded references (macros) to other named params, preceded with a $ sign. All macros are evaluated when each config is run (vs. when the config file is initially read). Check the example above to see how the <code><code>$dir</code></code> and <code><code>$name</code></code> variables are used (which correspond to the current build directory and build name, respectively).</dt>
<dd>
</dd>
<dt id="Any-arbitrary-variable-can-be-declared-and-then-used-as-a-macro-like-common-is-used-in-the-example-above-.-Typical-variable-name-syntax-rules-apply-no-spaces-etc-.-They-can-appear-in-any-order-in-the-confg-file-you-do-not-have-to-declare-a-variable-before-using-it-as-long-as-it-appears-somewhere-in-the-config-file">Any arbitrary variable can be declared and then used as a macro (like <code><code>$common</code></code> is used in the example above). Typical variable name syntax rules apply (no spaces, etc). They can appear in any order in the confg file (you do not have to declare a variable before using it, as long as it appears somewhere in the config file).</dt>
<dd>
</dd>
</dl>
<p>* Note that the config file is also used by <i>SBA</i> to store some data about each build (eg. last built version and date). Therefore it should be writeable by the system. If it isn't, there will be no way to track the last built version, which may trigger a rebuild on each run. ** It is a good idea to keep backups of your INI config files in case anything goes completely awry and corrupts the original config **</p>
<h4 id="Per-build-Config-parameters">Per-build Config parameters:</h4>
<p>These can appear in the [build-default] block or any build [named-block]. Note that the command names (clean/build/etc) are just arbitrary, meaning you can run any command you want on any step. The actual commands are simply passed to your system shell to execute, so they can be anything. There are also some built-in command you can use -- see <a href="#FTP-Distribution">"FTP Distribution"</a> and <a href="#Zip-Archive-Utility">"Zip Archive Utility"</a>, below.</p>
<p>Builds are executed in the order in which they appear in the config file. A failed build should not prevent other builds from executing.</p>
<p>Build commands are run consecutively: clean -> build -> deploy -> distrib -> final. They are dependent on each other, meaning a failed step will halt any futher processing of that build configuration.</p>
<dl>
<dt id="name-default:-block-name"><b>name</b> <i>(default: "[<code><code>block-name</code></code>]")</i></dt>
<dd>
<p>A unique name for this build. By default the <code><code>name</code></code> is taken from the title of the config [block], but you can set one explicitly as well.</p>
</dd>
<dt id="dir-default"><b>dir</b> <i>(default: "")</i></dt>
<dd>
<p>Root directory for this build. If specified, the script will make sure it exists (and try to create it if it doesn't) before processing any commands.</p>
</dd>
<dt id="clean-build-deploy-distrib-final-default"><b>clean</b> / <b>build</b> / <b>deploy</b> / <b>distrib</b> / <b>final</b> <i>(default: "")</i></dt>
<dd>
<p>Commands to execute for a package. Commands specified in the [build-default] block will execute for each build, unless the same command is specified in the build-specific [named-block]. A blank value will disable the command. At least one command should be non-blank, otherwise nothing will be done for the build config.</p>
<p>To determine successful execution of a command, it should return a standard system exit code when run. Usually this means zero for sucess and anything else for failure. Almost any common command-line tool will follow this standard.</p>
<p>There are also some built-in command you can use -- see <a href="#FTP-Distribution">"FTP Distribution"</a> and <a href="#Zip-Archive-Utility">"Zip Archive Utility"</a>, below.</p>
</dd>
<dt id="incremental-default:-0-false"><b>incremental</b> <i>(default: 0 (false))</i></dt>
<dd>
<p>Set to 1 to skip clean step, 0 to always clean first.</p>
</dd>
<dt id="force-default:-0-false"><b>force</b> <i>(default: 0 (false))</i></dt>
<dd>
<p>Set to 1 to always run this config, even if no new version was detected. This is like the global --force option, but per-configuration.</p>
</dd>
<dt id="enable-default:-1"><b>enable</b> <i>(default: 1)</i></dt>
<dd>
<p>Set to 0 to disable this build, 1 to enable.</p>
</dd>
</dl>
<p>Some parmeters are written back to the config file after each build by <i>SBA</i> itself, although you could set these manually if you wanted to. Currently only the <code><code>last_built_ver</code></code> has any real significance, the rest are just a log for now.</p>
<dl>
<dt id="last_built_ver"><b>last_built_ver</b></dt>
<dd>
<p>Keeps track of the last version successfully built. This is whatever string is used to keep track of versions from the VCS system. Eg. SVN would typically use the Revision number (eg. from <code><code>svn info</code></code>), or for Git it could be the last commit's SHA1 reference (eg. from <code><code>git ls-remote . HEAD</code></code>). You could provide a starting value here if you want to avoid rebuilding on the first run of your config file.</p>
</dd>
<dt id="last_built_dt"><b>last_built_dt</b></dt>
<dd>
<p>Date & time of last successful build.</p>
</dd>
<dt id="last_run_dt"><b>last_run_dt</b></dt>
<dd>
<p>Date & time of last run of this config.</p>
</dd>
<dt id="last_run_stat"><b>last_run_stat</b></dt>
<dd>
<p>Status code from last run/build attempt. Explained:</p>
<pre><code><code> <span class="number">0</span> <span class="operator">=</span> <span class="variable">unbuilt</span><span class="operator">;</span> <span class="number">1</span><span class="operator">-</span><span class="number">5</span> <span class="operator">=</span> <span class="variable">started</span> <span class="variable">step</span><span class="operator">;</span> <span class="number">10</span><span class="operator">-</span><span class="number">50</span> <span class="operator">=</span> <span class="variable">finished</span> <span class="variable">step</span><span class="operator">;</span> <span class="number">110</span><span class="operator">-</span><span class="number">150</span> <span class="operator">=</span> <span class="variable">error</span> <span class="variable">during</span> <span class="variable">step</span><span class="operator">;</span>
<span class="variable">where</span> <span class="variable">step</span><span class="operator">:</span> <span class="number">1</span><span class="operator">=</span><span class="variable">clean</span><span class="operator">;</span> <span class="number">2</span><span class="operator">=</span><span class="variable">build</span><span class="operator">;</span> <span class="number">3</span><span class="operator">=</span><span class="variable">deploy</span><span class="operator">;</span> <span class="number">4</span><span class="operator">=</span><span class="variable">distrib</span><span class="operator">;</span> <span class="number">5</span><span class="operator">=</span><span class="variable">finish</span><span class="operator">.</span>
<span class="variable">Eg</span><span class="operator">.</span> <span class="number">40</span><span class="operator">=</span><span class="variable">finished</span> <span class="variable">distrib</span><span class="operator">,</span> <span class="keyword">or</span> <span class="number">110</span><span class="operator">=</span><span class="variable">error</span> <span class="variable">during</span> <span class="variable">clean</span>
</code></code></pre>
</dd>
</dl>
<h2 id="Built-in-Utilities-for-Scripted-Builds">Built-in Utilities for Scripted Builds</h2>
<p><i>SBA</i> provides some built-in utilities which can be used as part of a build step. You can call them just as you would any other system command. To ensure uniqueness, the build-in commands start with <code><code>sba_</code></code>, eg. <code><code>sba_ftp</code></code> and <code><code>sba_zip</code></code>.</p>
<h3 id="FTP-Distribution">FTP Distribution</h3>
<p>To use the built-in FTP client to upload files, specify the follwing command for any of the build steps:</p>
<p><code><code>sba_ftp ftp_server ftp_user ftp_pass dest_folder [bin|asc] [perm_mask] file/pattern [file/pattern] [...]</code></code></p>
<p>Where:</p>
<dl>
<dt id="ftp_server-ftp_user-ftp_pass"><b>ftp_server</b>, <b>ftp_user</b>, <b>ftp_pass</b></dt>
<dd>
<p>Are the server host name, user name, and password, respectively. User should have permissions to upload files and, optionally, create directories and modify permissions (chmod).</p>
</dd>
<dt id="dest-folder"><b>dest folder</b></dt>
<dd>
<p>Remote folder to upload files into. Relative or absolute, whatever the server will understand. For now all files must go into the same folder. Will attempt to create this folder on remote system if it doesn't exist (and optionaly apply permission mask using chmod, see below).</p>
</dd>
<dt id="bin-asc"><b>bin|asc</b></dt>
<dd>
<p>File transfer mode to use, binary or ascii. This parameter is optional. Default is binary.</p>
</dd>
<dt id="perm_mask"><b>perm_mask</b></dt>
<dd>
<p>Numeric permission mask for chmod after file upload or directory creation, if your server requires it (eg. <i>754</i> for public access). This parameter is optional. Set to zero, the default, to disable modifying permissions at all.</p>
</dd>
<dt id="file-pattern"><b>file/pattern</b></dt>
<dd>
<p>The file(s) to upload, with absolute or relative path (relative is to current working folder). Can include wildcards, as long as the system is able to expand that to a list of files. Separate multiple entries with a space. Only files are allowed here, no directories.</p>
</dd>
</dl>
<h3 id="Zip-Archive-Utility">Zip Archive Utility</h3>
<p>The built-in zip archive creator is very simple (and simplistic). To use it, specify this for a build step's command:</p>
<p><code><code>sba_zip [-o archive-name.zip] file/dir [file/dir] [...]</code></code></p>
<p>Where:</p>
<dl>
<dt id="o-path-and-archive-name.zip"><b>-o</b> <path/and/archive/name.zip></dt>
<dd>
<p>Optionally, specify the resulting archive name and location, with absolute or relative path (relative is to current working folder). By default, the archive is named as the first added entry (file or folder name) plus ".zip" apppended, and placed in the same directory. For example, if you use this command: <code><code>sba_zip path/to/binfile.exe</code></code> The resulting archive will be <i>path/to/binfile.exe.zip</i> . If a wildcard is used, then the first actual resolved name becomes the archive's base name. For example: <code><code>sba_zip path/to/*.exe</code></code> Assuming that folder contains <i>binfile-a.exe</i> and <i>binfile-z.exe</i>, the resulting archive name will be <i>path/to/binfile-a.exe.zip</i>.</p>
</dd>
<dt id="file-dir"><b>file/dir</b></dt>
<dd>
<p>The file(s) of folder(s) to include in the archive, with absolute or relative path (relative is to current working folder). Can include wildcards, as long as the system is able to expand that to a list of files. Separate multiple entries with a space.</p>
</dd>
</dl>
<h3 id="Embedding-system-commands">Embedding system commands</h3>
<p>Note that you could pass a system command as an argument value by enclosing it in backticks (`...`) which is standard Perl way to capture output from the system. Eg. set <i>ftp pass</i> to <code><code>`cat ~/mypass.txt`</code></code> to read the contents of mypass.txt in current user's home directory, and then use it as the password parameter value.</p>
<pre><code><code> As another example, if the file "myftp" contains three words:
my.server.org myuser mypass
Then: sba_ftp `cat ~/myftp` /dest/folder ./file/to/upload.ext
Results in: sba_ftp my.server.org myuser mypass /dest/folder ./file/to/upload.ext
</code></code></pre>
<h2 id="E-Mail-Notifications">E-Mail Notifications</h2>
<p>To receive a summary or the completed job, use the notify-* options <a href="#Notification-Options">described above</a> to specify a destination e-mail address (or several, separated by comma) and a <b>server</b> to use for sending mail. The summary includes what is normally displayed on the console when you run <code><code>sba.pl</code></code>. The subject line includes an overall status and build totals. By default notices are only sent when something was actually done (build/distributed), although you can override this using <code><code>--notify-always</code></code> or <code><code>notify-always = 1</code></code> in the config file.</p>
<p>The simplest scenario is if your server is local or otherwise can authenticate you w/out logging in (eg. IP address). You can also specify a user/pass if necessary. The <code><code>notify-usetls</code></code> option provides some extra security, but might not work due to certificate issues with the underlying Perl SSL module.</p>
<h2 id="Requires">Requires</h2>
<p>Perl 5.10.01 or higher. Windows or Linux (& probably OS X). Perl modules (most are standard):</p>
<dl>
<dt id="Config::IniFiles"><a href="http://search.cpan.org/search?query=config-inifile">Config::IniFiles</a></dt>
<dd>
</dd>
<dt id="Mail::Sender"><a href="http://search.cpan.org/~jenda/Mail-Sender/Sender.pm">Mail::Sender</a></dt>
<dd>
</dd>
<dt id="Net::FTP"><a href="http://search.cpan.org/search?query=net-ftp">Net::FTP</a></dt>
<dd>
</dd>
<dt id="Archive::Zip"><a href="http://search.cpan.org/search?query=archive-zip">Archive::Zip</a></dt>
<dd>
</dd>
<dt id="Getopt::Long"><a href="http://search.cpan.org/search?query=getopt-long">Getopt::Long</a></dt>
<dd>
</dd>
<dt id="Pod::Usage"><a href="http://search.cpan.org/search?query=pod-usage">Pod::Usage</a></dt>
<dd>
</dd>
<dt id="Data::Dump-for-debug-only"><a href="http://search.cpan.org/search?query=data-dump">Data::Dump</a> (for debug only)</dt>
<dd>
</dd>
</dl>
<p>Make sure your <b>environment</b> is prepared for the build jobs (eg. PATH is set properly, <code><code>make</code></code> is available, etc). You may want a wrapper shell/batch script which first sets up the environment before calling this program.</p>
<p>E-Mail <b>notifications</b> require a mail server capable of relaying the mail (see <a href="#E-Mail-Notifications">"E-Mail Notifications"</a>).</p>
<p>Windows users may want cygwin/msys or some other version of GNU tools in the current PATH. If you are building software, you probably have this already. You can always try it w/out that and see if it complains about any missing system commands. The GnuWin32 collection of <a href="http://gnuwin32.sourceforge.net/packages/coreutils.htm">CoreUtils for Windows</a> is highly recommended.</p>
<h2 id="Author">Author</h2>
<pre><code><code> Maxim Paperno - MPaperno@WorldDesign.com
https://github.com/mpaperno/SBA
</code></code></pre>
<h2 id="Copyright-License-and-Disclaimer">Copyright, License, and Disclaimer</h2>
<p>Copyright (c) 2014 by Maxim Paperno. All rights reserved.</p>
<pre><code><code> <span class="variable">This</span> <span class="variable">program</span> <span class="variable">is</span> <span class="variable">free</span> <span class="variable">software</span><span class="operator">:</span> <span class="variable">you</span> <span class="variable">can</span> <span class="variable">redistribute</span> <span class="variable">it</span> <span class="keyword">and</span><span class="regex">/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http:/</span><span class="operator">/</span><span class="variable">www</span><span class="operator">.</span><span class="variable">gnu</span><span class="operator">.</span><span class="variable">org</span><span class="operator">/</span><span class="variable">licenses</span><span class="operator">/>.</span>
</code></code></pre>
</body>
</html>