-
Notifications
You must be signed in to change notification settings - Fork 34
/
Build.html
1019 lines (847 loc) · 29.2 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
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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 https://mozilla.org/MPL/2.0/
*
* Copyright (C) 2009-2024, Peter Johnson (gravatar.com/delphidabbler).
*
* Instructions for building CodeSnip from source.
-->
<html xmlns="https://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>
Building CodeSnip
</title>
<style type="text/css">
body {
font-family: sans-serif;
}
code, pre {
font-size: 1rem;
}
dt.spaced {
margin-top: 0.5em;
}
h1 {
text-align: center;
}
h2 {
padding-bottom: 0.25em;
border-bottom: 1px silver solid;
}
.indent {
margin-left: 2em;
}
ul.spaced li,
ol.spaced li {
margin-top: 0.5em;
}
p, div.spaced {
padding: 0;
margin: 0.5em 0;
}
.note, .cmd {
padding: 0.25em;
border: 1px solid silver;
}
.cmd {
background-color: #eef;
font-style: none;
}
.note {
background-color: #ffffcc;
font-style: italic;
}
.cmd {
margin-left: 2em;
margin-right: 2em;
font-weight: bold;
}
.prompt {
color: blue;
}
</style>
</head>
<body>
<h1>
CodeSnip Build Instructions
</h1>
<h2>
Introduction
</h2>
<p>
<em>CodeSnip</em> is written in Object Pascal and is targeted at Delphi
XE. Compilation with other compilers is not guaranteed.
</p>
<p class="note">
For an explanation of why <em>CodeSnip</em> still uses Delphi XE see
<a
href="https://github.com/delphidabbler/codesnip-faq/blob/master/SourceCode.md#faq-11"
>FAQ 11</a> of the CodeSnip Compiling & Source Code FAQs.
</p>
<p>
The are currently two editions of <em>CodeSnip</em>: the standard edition and
the portable edition. They both share the same code base: the different
editions are created using conditional compilation. These instructions show
how to build either edition.
</p>
<h2>
Dependencies
</h2>
<p>
Several DelphiDabbler and other 3rd party libraries and components are
required to compile <em>CodeSnip</em>. They are all included in the code
repository in the <code>Src/3rdParty</code> directory.
</p>
<p>
It goes without saying that you will also need the RTL and VCL that ships with
Delphi.
</p>
<h2>
Build Tools
</h2>
<p>
The following tools are required to build <em>CodeSnip</em>.
</p>
<h3>
Delphi
</h3>
<p>
All the following tools that ship with Delphi XE are required:
</p>
<dl class="indent">
<dt class="spaced">
<code>MAKE</code>
</dt>
<dd>
The make tool – do not use the Microsoft make tool.
</dd>
<dt class="spaced">
<code>DCC32</code>
</dt>
<dd>
The Delphi command line compiler.
</dd>
<dt class="spaced">
<code>BRCC32</code>
</dt>
<dd>
The Borland resource compiler. Used to compile various resource source
(<code>.rc</code>) files.
</dd>
<dt class="spaced">
<code>GenTLB</code>
</dt>
<dd>
Type library generator. Used to create the <code>ExternalObj.tlb</code> type
library from source code in <code>ExternalObj.ridl</code>.
</dd>
<dt class="spaced">
<code>TLibImpl</code>
</dt>
<dd>
Type library importer tool. Used to create a Pascal unit that describes
code contained in <code>ExternalObj.ridl</code>.
</dd>
</dl>
<p>
The following environment variables are associated with these tools:
</p>
<dl class="indent">
<dt class="spaced">
<code>DELPHIROOT</code> - required unless <code>DELPHIXE</code> is set.
</dt>
<dd>
Should be set to the install directory of the version of Delphi being
used. <code>DCC32</code>, <code>BRCC32</code> and <code>TLibImpl</code>
are expected to be in the <code>Bin</code> sub-directory of
<code>DELPHIROOT</code>.
</dd>
<dt class="spaced">
<code>DELPHIXE</code> - optional
</dt>
<dd>
This environment variable can be set to the Delphi XE install
directory. When <code>DELPHIXE</code> is defined
<code>DELPHIROOT</code> will be set to the value of
<code>DELPHIXE</code>.
</dd>
</dl>
<h3>
DelphiDabbler Version Information Editor (VIEd)
</h3>
<p>
This tool is used to compile version information (<code>.vi</code>) files and
any associated macro file(s) into intermediate resource source
(<code>.rc</code>) files. Version 2.15.0 or later is required. Version
Information Editor can be obtained from
<a
href="https://github.com/delphidabbler/vied/releases"
>https://github.com/delphidabbler/vied/releases</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>
DelphiDabbler HTML Resource Compiler (HTMLRes)
</h3>
<p>
HTMLRes is used to compile <code>HTML.hrc</code> which adds various
HTML, JavaScript, CSS and images to HTML resources. Version 1.1 or later
is required.
The HTML Resource Compiler can be obtained from
<a
href="https://github.com/delphidabbler/htmlres/releases"
>https://github.com/delphidabbler/htmlres/releases</a>.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>HTMLRESROOT</code> environment variable.
</p>
<h3>
Inno Setup
</h3>
<p>
The Unicode version of the Inno Setup <strong>v5</strong> command line
compiler is needed to create <em>CodeSnip</em>'s install program. v5.5.2(u) or
later is required.
</p>
<p class="note">
<strong>Warning:</strong> Do not use Inno Setup v6. This will fail to compile
the setup script. Inno Setup 6 does not support Windows 2000 or XE, while
<em>CodeSnip</em> still does.
</p>
<p>
You can get Inno Setup at <a
href="https://www.jrsoftware.org/isinfo.php"
>https://www.jrsoftware.org/isinfo.php</a>. Choose the Unicode version and
ensure that the ISPP pre-processor is installed. 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 path to Unicode Inno Setup's install directory will be looked for in the
<code>INNOSETUP_U</code> environment variable, or, if that is not set, in the
<code>INNOSETUP</code> environment variable. If neither of these is set then
the correct version of Inno Setup is expected to be on the path.
</p>
<p>
<strong>Note:</strong> Inno Setup is not required if you are creating only the
portable edition of <em>CodeSnip</em> since that edition does not have an
install program.
</p>
<h3>
Microsoft HTML Help Compiler (HHC)
</h3>
<p>
This command line compiler is supplied with Microsoft HTML Help Workshop. It
is used to compile the <em>CodeSnip</em> help file.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>HHCROOT</code> environment variable.
</p>
<h3>
Zip
</h3>
<p>
This program is used to create <em>CodeSnip</em>'s release file. The InfoZip
version of zip is required. 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 class="note">
<strong>Warning:</strong> The above link is <code>http</code> only. If you or
your browser object to the insecure link you can download an identical version
from delphidabbler.com, using the <code>https</code> protocol. See <a
href="https://delphidabbler.com/extras/info-zip"
>https://delphidabbler.com/extras/info-zip</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>
<p>
You do not need Zip if you do not intend to create release files.
</p>
<h2>
Preparation
</h2>
<h3>
Configure the environment.
</h3>
<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>
<h4>
Step 1
</h4>
<p>
Configure the required environment variables. Compilation will fail if these
environment variables are not set:
</p>
<ul>
<li>
<code>DELPHIROOT</code> <strong>or</strong> <code>DELPHIXE</code>
</li>
</ul>
<h4>
Step 2
</h4>
<p>
Update the <code>PATH</code> environment variable to include
<code>%DELPHIROOT%\Bin</code> as its first path, i.e. do:
</p>
<pre class="cmd"><span class="prompt">></span> set PATH=%DELPHIROOT%\Bin;%PATH%</pre>
<p>
You do not have to do this but it means you can run
<code>Make</code> from the command line without having to specify its path
every time.
</p>
<h4>
Step 3
</h4>
<p>
Set any of the following environment variables that are needed to specify
the path to any tools that cannot be found on the path:
</p>
<ul>
<li>
<code>VIEDROOT</code>
</li>
<li>
<code>HTMLRESROOT</code>
</li>
<li>
<code>INNOSETUP_U</code> or <code>INNOSETUP</code>
</li>
<li>
<code>HHCROOT</code>
</li>
<li>
<code>ZIPROOT</code>
</li>
</ul>
<h3>
Get the Source Code
</h3>
<p>
The source code is maintained in the <code><a href="https://github.com/delphidabbler/codesnip">delphidabbler/codesnip</a></code> Git respository on GitHub. Source code can be obtained in three ways:
</p>
<ol>
<li>
<p>
Fork the project from GitHub and then clone your forked repository.
</p>
</li>
<li>
<p>
Clone the existing repository using:
</p>
<pre class="cmd"><span class="prompt">></span> git clone https://github.com/delphidabbler/codesnip.git</pre>
</li>
<li>
<p>
Download the source of a specific release from the project's <a href="https://github.com/delphidabbler/codesnip/releases">Releases</a> section on GitHub – just choose the version you want.
</p>
</li>
</ol>
<p>
If you are intending to contribute code to the project please read the most up to date version of the project's <a href="https://github.com/delphidabbler/codesnip/blob/develop/README.md">read-me file</a> before doing so.
</p>
<p class="note">
<strong>Important:</strong> If you are planning to fork <em>CodeSnip</em> and to develop and release your own application derived from the CodeSnip code base then some changes to the code are required under the terms of the <em>CodeSnip</em> license. See the <a href="#conditions">Conditions For Release of Modified Code</a> section below for details.
</p>
<h3>
Configure the Source Tree
</h3>
<p>
After forking the repository or downloading and extracting the source code you should have the following directory structure:
</p>
<pre>./
|
+-- Docs - documentation
| |
| +-- Design - documents concerning program design
| |
| +-- FileFormats - documentation of CodeSnip's file formats
|
+-- Src - main CodeSnip source code
| |
| +-- 3rdParty - third party & DelphiDabbler library source code
| |
| +-- AutoGen - receives automatically generated code
| |
| +-- Help - help source files
| | |
| | +-- CSS - CSS code for help files
| | |
| | +-- HTML - HTML files included in help file
| | |
| | +-- Images - images included in help file
| |
| +-- Install - setup script and support code
| | |
| | +-- Assets - files required for inclusion in install program
| |
| +-- Res - container for files that are embedded in resources
| |
| +-- CSS - CSS files
| |
| +-- HTML - HTML files
| |
| +-- Img - image files
| | |
| | +-- AltBranding - image files used for 3rd party branding
| | |
| | +-- Branding - image files used for CodeSnip branding only
| | |
| | +-- Egg - image files for 'Easter Egg'
| |
| +-- Misc - other resources
| |
| +-- Scripts - scripting files
| |
| +-- 3rdParty - 3rd party scripting files
|
+-- Tests - contains test code
|
+-- Src - test source code
|
+-- DUnit - test source code that uses the DUnit framework</pre>
<p>
If, by chance you also have a <code>_build</code> directory don't worry - all will become clear.
Git users may also see the usual <code>.git</code> hidden
directory. If you have done some editing in the Delphi IDE you may also see
occasional hidden <code>__history</code> folders.
</p>
<p>
Before you can get hacking, you need to prepare the code tree. Open a command
console then run any script you may have created to set the required environment variables. Now navigate into the <code>Src</code> sub-folder and do:
</p>
<pre class="cmd"><span class="prompt">></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. If this is the case try:
</p>
<pre class="cmd"><span class="prompt">></span> %DELPHIROOT%\Bin\Make config</pre>
<p>
or
</p>
<pre class="cmd"><span class="prompt">></span> %DELPHIXE%\Bin\Make config</pre>
<p>
depending on which environment variable you have set.
</p>
<p>
Once <code>Make config</code> has run your folder structure should
have acquired the following new folders, if they weren't present already:
</p>
<pre>./
|
+-- _build - contains all the build files
| |
| +-- bin - receives object files for CodeSnip
| |
| +-- exe - receives executable code and compiled help file
| |
| +-- release - receives release files
| |
| +-- ~tmp~ - store for temp files ceated in release process
|
...</pre>
<p>
If the <code>_build/bin</code> folder already existed, it will have been emptied.
In addition, <code>Make</code> will have created a <code>.cfg</code> file from a
template in the <code>Src</code> folder. This <code>.cfg</code> file is needed
for DCC32 to run correctly. The file will be ignored by Git.
</p>
<h4>
Using the Delphi IDE
</h4>
<p>
If you are intending to use the Delphi IDE to compile code, you should also
do:
</p>
<pre class="cmd"><span class="prompt">></span> Make resources
<span class="prompt">></span> Make typelib
<span class="prompt">></span> Make autogen</pre>
<p>
This compiles the resource files that the IDE needs to link into compiled
executables, compiles the type library from IDL code and generates the
Pascal file that provides an interface to the type library.
</p>
<p>
If you wish to build the portable edition of <em>CodeSnip</em> you also need
to do:
</p>
<pre class="cmd"><span class="prompt">></span> Make -DPORTABLE resources</pre>
<p>
and define the <code>PORTABLE</code> conditional define in <em>Project
Options</em>. The standard name for the portable exe file is
<code>CodeSnip-p.exe</code>, but the IDE will generate
<code>CodeSnip.exe</code>. You can rename the file manually.
</p>
<p>
After you have gone through these steps you can edit Pascal code and test
compile from the Delphi IDE. However if you change any files compiled into resources, or the type library, or run a clean up, then you must repeat the
above steps and do a complete build from the IDE.
</p>
<p>
Note that building with the make file insted of the IDE performs all the above
steps automatically.
</p>
<h2>
Building CodeSnip
</h2>
<p>
This section guides you through building <em>CodeSnip</em> from the command
line, not from the IDE.
</p>
<p>
You have several options:
</p>
<ol class="spaced">
<li>
Build the <em>CodeSnip</em> Executable
</li>
<li>
Build the Help File.
</li>
<li>
Build the Setup Program.
</li>
<li>
Build the Release Zip File.
</li>
<li>
Build and Release Everything.
</li>
<li>
Clean Up.
</li>
</ol>
<p>
Each of these options is described below. All except options 5 and 6 assume that
<code>Make config</code> has been run.
</p>
<p class="note">
<strong>Note:</strong> This information applies only to building
<em>CodeSnip</em> itself, not to building and using the code in the
<code>Test</code> directory.
</p>
<h3>
Build the CodeSnip Executable
</h3>
<p>
This is the most common build and has a simple command:
</p>
<pre class="cmd"><span class="prompt">></span> Make codesnip</pre>
<p>
This is the same as doing this sequence of commands:
</p>
<pre class="cmd"><span class="prompt">></span> Make typelib
<span class="prompt">></span> Make resources
<span class="prompt">></span> Make autogen
<span class="prompt">></span> Make pascal</pre>
<p>
The <em>CodeSnip</em> executable, named <code>CodeSnip.exe</code> will be
placed in the <code>_build\exe</code> folder.
</p>
<h4>
Portable edition
</h4>
<p>
To build the portable edition of <em>CodeSnip</em> you must either define the
<code>PORTABLE</code> environment variable or do:
</p>
<pre class="cmd"><span class="prompt">></span> Make -DPORTABLE codesnip</pre>
<p>
Again the executable is placed in the <code>_build\exe</code> folder, but this time
it is named <code>CodeSnip-p.exe</code>
</p>
<h3>
Build the Help File
</h3>
<p>
To build the help file just do
</p>
<pre class="cmd"><span class="prompt">></span> Make help</pre>
<p>
The compiled help file will be written to the <code>_build\exe</code> folder.
</p>
<p>
The same help file is used for the standard and portable editions.
</p>
<h3>
Build the Setup Program
</h3>
<p>
The setup program requires that the <em>CodeSnip</em> executable and the
compiled help file are already present in the <code>_build\exe</code> directory.
</p>
<p>
As an aside, you can make all the required files by doing:
</p>
<pre class="cmd"><span class="prompt">></span> Make exes</pre>
<p>
Once you have built all the required files you build the setup file by
doing:
</p>
<pre class="cmd"><span class="prompt">></span> Make setup</pre>
<p>
The setup program is named <code>CodeSnip-Setup-x.x.x.exe</code>, where
x.x.x is the version number extracted from <em>CodeSnip</em>'s version
information. It is placed in the <code>_build\exe</code> directory.
</p>
<p>
If the <em>SpecialBuild</em> string is defined in <em>CodeSnip</em>'s
version information the string will be appended to the setup file name like
this <code>CodeSnip-Setup-x.x.x-SPECIALBUILD</code>.
</p>
<h4>
Portable edition
</h4>
<p>
<em>CodeSnip</em>'s portable edition does not use a setup file so <code>Make
setup</code> does nothing except print a message if it is run when the
<code>PORTABLE</code> symbol is defined.
</p>
<h3>
Build the Release Zip File
</h3>
<p>
Make can create zip files containing all the files that are included in a release.
Zip files are written to the <code>_build\release</code> directory.
</p>
<h4>
Standard edition
</h4>
<p>
The release zip file for the standard edition requires that the setup files is already
present in the <code>_build\exe</code> directory.
</p>
<p>
The release file includes the setup file along with <code>ReadMe.txt</code>
that is automatically generated from <code>Docs\ReadMe-standard.txt</code>.
</p>
<p>
Build the release by doing:
</p>
<pre class="cmd"><span class="prompt">></span> Make release</pre>
<p>
By default the release file is named <code>codesnip-exe.zip</code>. You can
change this name by defining the <code>RELEASEFILENAME</code> macro or
enviroment variable. For example, you can name the file
<code>MyRelease.zip</code> by doing:
</p>
<pre class="cmd"><span class="prompt">></span> Make -DRELEASEFILENAME=MyRelease release</pre>
<p>
Note that the <code>.zip</code> extension should not be included in the file name.
</p>
<h4>
Portable edition
</h4>
<p>
The release zip file for the portable edition cannot be created until the
<em>CodeSnip</em> excutable and the compiled help file are already present in the
<code>_build\exe</code> directory.
</p>
<p>
The release file includes the portable executable file, <code>CodeSnip-p.exe</code>,
the help file <code>CodeSnip.chm</code>, <code>Docs\License.html</code> and
<code>ReadMe.txt</code> that is automatically generated from
<code>Docs\ReadMe-portable.txt</code>.
</p>
<p>
Build the portable release by doing:
</p>
<pre class="cmd"><span class="prompt">></span> Make -DPORTABLE release</pre>
<p>
By default the release file is named <code>dd-codesnip-portable.zip</code>.
You can change this name by defining the <code>RELEASEFILENAME</code> macro or
enviroment variable. For example, you can name the file
<code>MyPortableRelease.zip</code> by doing:
</p>
<pre class="cmd"><span class="prompt">></span> Make -DPORTABLE -DRELEASEFILENAME=MyPortableRelease release</pre>
<p>
Once again note that the <code>.zip</code> extension should not be included in the file name.
</p>
<p class="note">
<strong>Warning:</strong> If you are building both the standard and portable
releases with custom file names, make sure you supply a different value of
the <code>RELEASEFILENAME</code> macro for each release, otherwise the last
built release will overwrite the first.
</p>
<h4>
Including version numbers in zip file names
</h4>
<p>
A version number can be suffixed to the release zip file name by defining the <code>VERSION</code> macro.
This macro works with both the <code>PORTABLE</code> and <code>RELEASEFILENAME</code> macros.
</p>
<p>
For example to appended version number 4.22.0 to the zip file name on a standard edition build, with the default
file name do:
</p>
<pre class="cmd"><span class="prompt">></span> Make -DVERSION=4.22.0 release</pre>
<p>
This will create a zip file named <code>codesnip-exe-4.22.0.zip</code>.
</p>
<p>
A more complex example would be to append the same version number to a portable edition build named <code>MyPortableRelease</code>. Do:
</p>
<pre class="cmd"><span class="prompt">></span> Make -DPORTABLE -DRELEASEFILENAME=MyPortableRelease -DVERSION=4.22.0 release</pre>
<p>
This time the resulting zip file will be named <code>MyPortableRelease-4.22.0.zip</code>.
</p>
<h3>
Build and Release Everything
</h3>
<p>
You can do a complete build of everything, and generate the release zip file
simply by doing:
</p>
<pre class="cmd"><span class="prompt">></span> Make</pre>
<p>
without specifying a target. This is the equivalent of:
</p>
<pre class="cmd"><span class="prompt">></span> Make config
<span class="prompt">></span> Make exes
<span class="prompt">></span> Make setup
<span class="prompt">></span> Make release</pre>
<p>
To perform a complete build of the portable edition of <em>CodeSnip</em> do
</p>
<pre class="cmd"><span class="prompt">></span> Make -DPORTABLE</pre>
<p>
Note that the <code>RELEASEFILENAME</code> and <code>VERSION</code> macros that can be used for customising
zip file names can be used here too.
</p>
<p>
There is also a quicker way to build a release, but you must provide a version number to use it. First navigate up
to the repository root. Then run
</p>
<pre class="cmd"><span class="prompt">></span> Deploy 9.9.9</pre>
<p>
where <code>9.9.9</code> is the release version number.
</p>
<p>
This command will build both the standard and portable executables, the help file, the standard edition setup file
and finally create the release zip files for both editions, with the release version number incorporated in the file names.
</p>
<p>
Using <code>Deploy 9.9.9</code> is the equivalent of doing:
</p>
<pre class="cmd"><span class="prompt">></span> cd Src
<span class="prompt">></span> Make -DVERSION=9.9.9
<span class="prompt">></span> Make -DPORTABLE -DVERSION=9.9.9
<span class="prompt">></span> cd ..</pre>
<h3>
Clean Up
</h3>
<p>
Various temporary files and directories are created by the IDE. These can be
deleted by running.
</p>
<pre class="cmd"><span class="prompt">></span> Make clean</pre>
<p class="note">
<strong>Warning:</strong> This command removes the <code>__history</code>
folders that Delphi uses to roll back to earlier versions of files.
</p>
<h2>
Running the Tests
</h2>
<p>
At present all tests use the <em>DUnit</em> unit testing framework and are
combined into a single test application.
</p>
<p>
To compile the tests, open the <code>Src\CodeSnip.groupproj</code> group
project file in the Delphi XE IDE. Now select the <em>CodeSnipTests.exe</em>
target in the project manager and compile.
</p>
<p>
If they were not already present <code>Bin</code> and <code>Exe</code>
sub-directories will have been created in the <code>Tests</code> directory.
The <code>Exe</code> directory contains the <em>DUnit</em> test program while
<code>Bin</code> contains intermediate binaries.
</p>
<p>
You can compile the tests as either a GUI application (default) or as a
console application. For details please see the comments in
<code>Tests\Src\DUnit\CodeSnipTests.dpr</code>.
</p>
<h2>
License
</h2>
<p>
The majority of <em>CodeSnip</em>'s original source code is licensed under the
<a
href="https://www.mozilla.org/MPL/2.0/"
>Mozilla Public License v2.0</a>. The are a few exceptions, mainly relating to
third party source code and image files. For full details of all applicable
licenses please read <code>License.html</code> in the <code>Docs</code>
directory.
</p>
<h2 id="conditions">
Conditions For Release of Modified Code
</h2>
<p>
If you are intending to release your own application based on the <em>CodeSnip</em> source code you <strong>must</strong> <em>either</em> change the source code as described below <em>or</em> seek written permission to use the DelphiDabbler CodeSnip branding. To seek such permission please use the <em>CodeSnip</em> <a href="https://github.com/delphidabbler/codesnip/issues">Issue Tracker</a> on GitHub.
</p>
<h3>
Required Changes
</h3>
<p>
The changes are required to remove DelphiDabbler CodeSnip copyrighted branding from the program, to prevent interference with existing CodeSnip installations and to remove any implied endorsement of the modified release. You <strong>must</strong>:
</p>
<ol>
<li>
<p>
Replace the files in the <code>Src\Res\Img\Branding</code> directory with copies of the identically named placeholder files in the <code>Src\Res\Img\AltBranding</code> directory. The placeholder files are Public Domain, so you may use them as-is, edit them or replace them. If you delete the files in <code>Src\Res\Img\Branding</code> without copying the placeholder files across then <em>CodeSnip</em> will fail to build.
</p>
</li>
<li>
<p>
Replace all relevant references, in source code and documentation, to the names "CodeSnip" and "DelphiDabbler" with your own company and program name. Relevant occurences are:
</p>
<ul>
<li>
Wherever the names may be displayed in the GUI.
</li>
<li>
Wherever the names may be displayed by the installer.
</li>
<li>
Wherever the names occur in directory names. In particular do not use the names in the program's <code>%ProgramData%</code> and <code>%AppData%</code> sub-directories.
</li>
<li>
Anywhere else that use of the names could imply endorsement of the modified code.
</li>
</ul>
</li>
<li>
<p>
Provide your own license file with content compatible with the requirements of the <em>CodeSnip</em> license as it relates to the code reused from the <em>CodeSnip</em> source tree. <strong>Do not</strong> edit or re-use <code>Docs/License.html</code>.
</p>