-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathBuild.html
719 lines (594 loc) · 18.3 KB
/
Build.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
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!--
* This Source Code Form is subject to the terms of the Mozilla Public License,
* v. 2.0. If a copy of the MPL was not distributed with this file, You can
* obtain one at http://mozilla.org/MPL/2.0/
*
* Copyright (C) 2009-2022, Peter Johnson (www.delphidabbler.com).
*
* Instructions for building PasHi and PasHiGUI.
-->
<html xmlns="https://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<html>
<head>
<title>
Building PasHi
</title>
<style>
body {
font-family: sans-serif;
}
dt.spaced {
margin-top: 0.5em;
}
h1 {
text-align: center;
}
h2 {
padding-bottom: 0.25em;
border-bottom: 1px silver solid;
}
ul.spaced li,
ol.spaced li {
margin-top: 0.5em;
}
p, pre, div.spaced {
padding: 0;
margin: 0.5em 0;
}
div.close-spaced, pre.close-spaced {
padding: 0;
margin: 0.25em 0;
}
.box, .cmd {
padding: 0.25em;
background-color: #eef;
border: 1px solid silver;
}
.cmd {
margin-left: 2em;
margin-right: 2em;
font-weight: bold;
}
.disabled {
color: gray;
}
.prompt {
color: blue;
}
</style>
</head>
<body>
<h1>
PasHi Build Instructions
</h1>
<h2>
Introduction
</h2>
<p>
These instructions show how to build the <em>PasHi</em> command line program
and, optionally, <em>PasHiGUI</em> - the GUI front end to <em>PasHi</em>.
</p>
<p>
The programs are written in Object Pascal and are targeted at Delphi XE.
</p>
<p>
The Delphi IDE can be used to modify the source and to perform test builds.
Final builds should be built using the provided makefiles.
</p>
<div class="box">
<p>
<strong>Note:</strong>
These instructions do not apply to versions of the program before release
v2.0.0.
</p>
</div>
<h2>
Dependencies
</h2>
<h3>
Libraries
</h3>
<h4>
PasHi
</h4>
<p>
No libraries are required to build <em>PasHi</em>
</p>
<h4>
PasHiGUI
</h4>
<p>
<em>PasHiGUI</em> requires <code>PJWdwState.pas</code> from the DelphiDabbler
Window State Components, v5.6.1 or later. A copy of the required file is
included in the <code>Src\GUI\Imported</code> directory. There is no need to
install the components into the DelphiIDE.
</p>
<h3>
Delphi VCL
</h3>
<p>
You need the relevant Delphi VCL in order to compile the programs.
</p>
<h2>
Build Tools
</h2>
<p>
The following tools are needed to build the programs.
</p>
<h3>
Delphi
</h3>
<p>
A copy of Delphi is required to build the object Pascal code. Delphi XE is the
preferred compiler.
</p>
<div class="box">
The code should be able to compile with Delphi XE and later. It is possible
that Delphi 2009 and 2010 may compile the code, but it hasn't been tested.
Versions earlier than Delphi 2009 are not suitable due to their lack of
Unicode support.
</div>
<p>
You can use the Delphi IDE to edit the code and test compile it. The
makefiles require the following command line tools:
</p>
<dl>
<dt class="spaced">
<code>DCC32</code>
</dt>
<dd>
<p>
The Delphi command line compiler.
</p>
<div class="box">
Not available with starter editions of Delphi.
</div>
</dd>
<dt class="spaced">
<code>RC</code>
</dt>
<dd>
<p>
The Microsoft resource compiler. Used to compile the main resource file.
</p>
</dd>
<dt class="spaced">
<code>BRCC32</code>
</dt>
<dd>
<p>
The Borland resource compiler. Used to compile version information
resources from temporary resource files emitted by VIEd (see below).
</p>
</dd>
</dl>
<div class="box">
We use two different resource compilers because <code>RC</code> fails to
compile resource files emitted by the Version Information Editor while
<code>BRCC32</code> can fail to compile <code>.manifest</code> files
correctly.
</div>
<p>
The following environment variables are associated with these tools:
</p>
<dl>
<dt class="spaced">
<code>DELPHIROOT</code> - required unless <code>DELPHIXE</code> is set.
</dt>
<dd>
<p>
Should be set to the install directory of the version of Delphi being
used. <code>DCC32</code>, <code>BRCC32</code> and <code>RC</code> are
expected to be in the <code>Bin</code> sub-directory of
<code>DELPHIROOT</code>.
</p>
</dd>
<dt class="spaced">
<code>DELPHIXE</code> - optional
</dt>
<dd>
<p>
If you are using Delphi XE this environment variable may be set to its
install directory. When <code>DELPHIXE</code> is specified
<code>DELPHIROOT</code> will be ignored and <code>DELPHIXE</code> will be
used instead.
</p>
</dd>
</dl>
<h3>
Borland MAKE
</h3>
<p>
This is the make tool that ships with Delphi. You can use any version that
works.
</p>
<h3>
DelphiDabbler Version Information Editor (VIEd)
</h3>
<p>
This tool is used to compile version information (<code>.vi</code>) files
into intermediate resource source (<code>.rc</code>) files. Version 2.11.2
or later is required. Version Information Editor can be obtained from
<a
href="https://delphidabbler.com/software/vied"
>https://delphidabbler.com/software/vied</a>.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>VIEDROOT</code> environment variable.
</p>
<h3>
Inno Setup
</h3>
<p>
The Unicode version of the Inno setup command line compiler is needed to
create <em>CodeSnip</em>'s install program. v5.4.0 (u) or later is required as
is a compatible version of the ISPP pre-processor. You can get Inno Setup with
ISPP at <a
href="https://www.jrsoftware.org/isinfo.php"
>https://www.jrsoftware.org/isinfo.php</a>. Choose the Unicode version. If you
already have the ANSI version the Unicode version can be installed alongside
it - just use a different install directory and program group name.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>INNOSETUP</code> environment variable.
</p>
<h3>
Zip
</h3>
<p>
This program is used to create release files. You can get a Windows command
line version at
<a
href="http://stahlforce.com/dev/index.php?tool=zipunzip"
>http://stahlforce.com/dev/index.php?tool=zipunzip</a>.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>ZIPROOT</code> environment variable.
</p>
<h2>
Preparation
</h2>
<h3>
Configure the environment.
</h3>
<p>
The first step is to configure the required <code>DELPHIROOT</code> or
<code>DELPHIXE</code> environment variables.
</p>
<p>
Next, set any of the optional <code>VIEDROOT</code>, <code>INNOSETUP</code>
and <code>ZIPROOT</code> environment variables that are needed to specify the
path to any tools that are not on the system path.
</p>
<p>
You can configure environment variables either by modifying your system
environment variables or by creating a batch file that you run before
performing the build.
</p>
<h3>
Get the Source Code
</h3>
<p>
If you don't already have it, you need to get the <em>PasHi</em> source code,
(which includes the source for <em>PasHiGUI</em>).
</p>
<p>
The source code is maintained in the <a
href="https://github.com/delphidabbler/pashi"
>delphidabbler/pashi</a> Git repository on GitHub. Either clone or fork the
repo into a directory on your computer.
</p>
<p>
Source code for <em>PasHi</em>'s latest release can be found in the
<em>master</em> branch while development code is maintained in the
<em>develop</em> branch. New features are developed in branches whose name
begins with <em>feature</em>. You can also download the code of one of the
releases by selecting the relevant tag.
</p>
<p class="box">
If you want to submit any modifications to the source code, please create a
new feature branch off the <em>develop</em> branch, commit your modifications
to it and then submit a pull request on GitHub.
</p>
<h3>
Configure the Source Tree
</h3>
<p>
After obtaining the source code you should have the following directory
structure:
</p>
<pre>./
|
+-- Config - config files to be installed with PasHi
|
+-- Docs - documentation
|
+-- Src - source code for PasHi
| |
| +-- Assets - assets required to build PasHi's resources
| |
| +-- GUI - source code of the GUI application, PasHiGUI
| | |
| | +-- Assets - assets required to build PasHiGUI's resources
| | |
| | +-- Imported - 3rd party source code used for GUI application
| |
| +-- Install - install program scripts
|
+-- Test - contains test file</pre>
<p>
Don't worry if you also have a <code>Build</code> directory and
sub-directories - all will become clear.
</p>
<p>
Before you can get hacking, you need to prepare the source code tree. Open a
command console and run any script you have created to set the required
environment variables. Then navigate into the <code>Src</code> sub-folder and
do:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make config</pre>
<p>
You may need to replace <code>Make</code> with the full path to
<code>Make</code> if it isn't on the path, or if the <code>Make</code> that
runs isn't the Borland / CodeGear / Embarcadero version. If this is the case
try:
</p>
<pre class="cmd"><span class="prompt">Src></span> "%DELPHIROOT%\Bin\Make" config</pre>
<p>
or
</p>
<pre class="cmd"><span class="prompt">Src></span> "%DELPHIXE%\Bin\Make" config</pre>
<p>
depending on which environment variable you have set.
</p>
<p>
Once <code>Make config</code> has completed, your folder structure should
have acquired a <code>Build</code> folder and sub-folders and now look like
this:
</p>
<pre>./
<strong>+-- Build - receives all files created by the build process
| |
| +-- Bin - receives object files and .res files for PasHi
| |
| +-- Exe - receives executable code
| |
| +-- Release - receives release files</strong>
<span class="disabled">|
+-- Config - config files to be installed with PasHi
|
+-- Docs - documentation
|
+-- Src - source code for PasHi
| |
| +-- Assets - assets required to build PasHi's resources
| |
| +-- GUI - source code of the GUI application, PasHiGUI
| | |
| | +-- Assets - assets required to build PasHiGUI's resources
| | |
| | +-- Imported - 3rd party source code used for GUI application
| |
| +-- Install - install program scripts
|
+-- Test - contains test file</span></pre>
<p>
<code>Make</code> will have created a <code>.cfg</code> file from the template
in the <code>Src</code> folder. <code>.cfg</code> files are needed for DCC32
to run correctly. This new file will be ignored by Git.
</p>
<p>
If you also want to compile <em>PasHiGUI</em> you must now do:
</p>
<pre class="cmd"><span class="prompt">Src></span> cd GUI
<span class="prompt">Src\GUI></span> Make config
<span class="prompt">Src\GUI></span> cd ..</pre>
<p>
This runs a separate makefile in the <code>Src\GUI</code> sub-directory and
further configures the source tree to enable <em>PasHiGUI</em> to be compiled.
The source tree should have been changed slightly to look like this:
</p>
<pre>./
<span class="disabled">+-- Build - receives all files created by the build process
| |
| +-- Bin - receives object files and .res files for PasHi
| |</span> <strong>|</strong>
<span class="disabled">| |</span> <strong>+-- GUI - receives object files and .res files for PasHiGUI</strong>
<span class="disabled">| |
| +-- Exe - receives executable code
| |
| +-- Release - receives release files
|
+-- Config - config files to be installed with PasHi
|
+-- Docs - documentation
|
+-- Src - source code for PasHi
| |
| +-- Assets - assets required to build PasHi's resources
| |
| +-- GUI - source code of the GUI application, PasHiGUI
| | |
| | +-- Assets - assets required to build PasHiGUI's resources
| | |
| | +-- Imported - 3rd party source code used for GUI application
| |
| +-- Install - install program scripts
|
+-- Test - contains test file</span></pre>
<p>
<code>Make</code> will also have created the required <code>.cfg</code> file
in the <code>Src\GUI</code> directory.
</p>
<p>
If you are intending to use the Delphi IDE to compile <em>PasHi</em>, you
should also do:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make resources</pre>
<p>
and, for <em>PasHiGUI</em>:
</p>
<pre class="cmd"><span class="prompt">Src></span> cd GUI
<span class="prompt">Src\GUI></span> Make resources
<span class="prompt">Src\GUI></span> cd ..</pre>
<p>
This compiles the resource files that the IDE needs to link into compiled
executables.
</p>
<p>
You are now ready to build the source.
</p>
<h2>
Building The Programs
</h2>
<h3>
Creating The Executables
</h3>
<p>
Once the source tree has been configured, and before you can build the
Pascal code, you must create the program's resources. For <em>PasHi</em> do:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make resources</pre>
<p>
and for <em>PasHiGUI</em> do:
</p>
<pre class="cmd"><span class="prompt">Src></span> cd GUI
<span class="prompt">Src\GUI></span> Make resources
<span class="prompt">Src\GUI></span> cd ..</pre>
<p>
And now you can build the Pascal code:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make pascal</pre>
<p>
or
</p>
<pre class="cmd"><span class="prompt">Src></span> cd GUI
<span class="prompt">Src\GUI></span> Make pascal
<span class="prompt">Src\GUI></span> cd ..</pre>
<p>
Should you want to build an executable from a clean source tree there is a
shortcut. Simply running:
</p>
<pre class="cmd"><span class="prompt">></span> Make</pre>
<p>
on its own is the same as doing:
</p>
<pre class="cmd"><span class="prompt">></span> Make config
<span class="prompt">></span> Make resources
<span class="prompt">></span> Make pascal</pre>
<p>
So, to build <em>PasHi</em> and <em>PasHiGUI</em> and place
<code>PasHi.exe</code> and <code>PasHiGUI.exe</code> in the
<code>Build\Exe</code> folder do this:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make
<span class="prompt">Src></span> cd GUI
<span class="prompt">Src\GUI></span> Make
<span class="prompt">Src\GUI></span> cd ..</pre>
<p>
There's a shortcut for building <em>PasHiGUI</em>: using the main makefile
just do:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make pashigui</pre>
<p>
When both the <em>PasHi</em> and <em>PasHiGUI</em> executables have been built
you can create the setup program. This is done from the main makefile with:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make setup</pre>
<h3>
Creating the Release zip file
</h3>
<p>
Once the setup program has been generated you can create a zip file containing
the setup program and the required documentation files. You create the zip
by doing:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make release</pre>
<p>
Note that this only works with the makefile in the <code>Src</code> directory:
the <code>release</code> target is not supported by
<code>Src\GUI\Makefile</code>.
</p>
<p>
By default the release file is called <code>dd-pashi.zip</code>. You can
change this name by defining the <code>RELEASEFILENAME</code> enviroment
variable or macro. For example, you can name the release
<code>MyRelease.zip</code> by doing:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make -DRELEASEFILENAME=MyRelease release</pre>
<p>
Release zip files are always placed in the <code>Build\Release</code>
directory.
</p>
<h3>
One-shot Build and Release
</h3>
<p>
When you are ready to create a release there is a shortcut you can use to
configure the source tree, build the executables and the setup program, and
finally package the release zip file. Use the following command:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make all</pre>
<p>
Once again you can change the release file name using the
<code>RELEASEFILENAME</code> environment variable or macro:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make -DRELEASEFILENAME=MyRelease all</pre>
<h2>
Clean Up
</h2>
<p>
Various temporary files and directories are created by the IDE. These can be
deleted by running:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make clean</pre>
<p>
This command is only available in the makefile in the <code>Src</code>
directory and acts on the whole source tree, including the <code>GUI</code>
sub-tree.
</p>
<p>
Be warned that this command removes the <code>__history</code> folders that
Delphi uses to record earlier versions of files.
</p>
<p>
<code>Make clean</code> leaves behind the files and directories created by
<code>Make config</code>. To delete these files and directories in addition to
performing a normal clean run:
</p>
<pre class="cmd"><span class="prompt">Src></span> Make deepclean</pre>
<p>
Once again this command operates on both the <code>Src</code> and
<code>Src\GUI</code> directories.
</p>
<h2>
Testing
</h2>
<p>
A test file, named <code>Test.pas</code>, is provided in the <code>Test</code>
directory. This file can be used to test the output of <em>PasHi</em>. It
contains some unusual but valid constructs that push the program to its
limits.
</p>
<p>
<code>Test.pas</code> was not designed to compile, so do not add it to the
project.
</p>
<h2>
License & Copyright
</h2>
<p>
If you are planning to re-use or modify any of the code, please see the file
<code>LICENSE.md</code> for an overview of the open source licenses that
apply to the source code.
</p>
<p>
<code>LICENSE.md</code> also provides copyright information.
</p>
</body>
</html>