+ For an explanation of why CodeSnip still uses Delphi XE see + FAQ 11 of the CodeSnip Compiling & Source Code FAQs. +
+The are currently two editions of CodeSnip: the standard edition and the portable edition. They both share the same code base: the different @@ -150,7 +160,7 @@
ExternalObj.idl.
+ code contained in ExternalObj.ridl.
- This tool is used to compile version information (.vi) files
- into intermediate resource source (.rc) files. Version 2.11.2
- or later is required.
- Version Information Editor can be obtained from
+ This tool is used to compile version information (.vi) files and
+ any associated macro file(s) into intermediate resource source
+ (.rc) files. Version 2.15.0 or later is required. Version
+ Information Editor can be obtained from
https://github.com/delphidabbler/vied/releases.
@@ -274,11 +284,19 @@
- This program is used to create CodeSnip's release file. - You can get a Windows command line version at + This program is used to create CodeSnip's release file. The InfoZip + version of zip is required. You can get a Windows command line version at http://stahlforce.com/dev/index.php?tool=zipunzip. + >http://stahlforce.com/dev/index.php?tool=zipunzip. +
+ +
+ Warning: The above link is http only. If you or
+ your browser object to the insecure link you can download an identical version
+ from delphidabbler.com, using the https protocol. See https://delphidabbler.com/extras/info-zip.
@@ -369,30 +387,34 @@
- The source code is maintained in the delphidabbler/codesnip Git respository on GitHub.
-
- If you are intending to contribute code to the project you need to:
+ The source code is maintained in the delphidabbler/codesnip Git respository on GitHub. Source code can be obtained in three ways:
development branch.
+ + Fork the project from GitHub and then clone your forked repository. +
+ Clone the existing repository using: +
+> git clone https://github.com/delphidabbler/codesnip.git
delphidabbler/codesnip repo.
+ + Download the source of a specific release from the project's Releases section on GitHub – just choose the version you want. +
- If you only intend to use the code for your own purposes you can still fork the repository as above. Alternatively you can download the source code from the project's Releases section on GitHub – just choose the version you want. + If you are intending to contribute code to the project please read the most up to date version of the project's read-me file before doing so. +
+ ++ Important: If you are planning to fork CodeSnip 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 CodeSnip license. See the Conditions For Release of Modified Code section below for details.
./
|
- +-- Docs - documentation
+ +-- Docs - documentation
| |
- | +-- Design - documents concerning program design
+ | +-- Design - documents concerning program design
| |
- | +-- FileFormats - documentation of CodeSnip's file formats
+ | +-- FileFormats - documentation of CodeSnip's file formats
|
- +-- Src - main CodeSnip source code
+ +-- Src - main CodeSnip source code
| |
- | +-- 3rdParty - third party & DelphiDabbler library source code
+ | +-- 3rdParty - third party & DelphiDabbler library source code
| |
- | +-- AutoGen - receives automatically generated code
+ | +-- AutoGen - receives automatically generated code
| |
- | +-- Help - help source files
+ | +-- Help - help source files
| | |
- | | +-- CSS - CSS code for help files
+ | | +-- CSS - CSS code for help files
| | |
- | | +-- HTML - HTML files included in help file
+ | | +-- HTML - HTML files included in help file
| | |
- | | +-- Images - images included in help file
+ | | +-- Images - images included in help file
| |
- | +-- Install - setup script and support code
+ | +-- Install - setup script and support code
| | |
- | | +-- Assets - files required for inclusion in install program
+ | | +-- Assets - files required for inclusion in install program
| |
- | +-- Res - container for files that are embedded in resources
+ | +-- Res - container for files that are embedded in resources
| |
- | +-- CSS - CSS files
+ | +-- CSS - CSS files
| |
- | +-- HTML - HTML files
+ | +-- HTML - HTML files
| |
- | +-- Img - image files
+ | +-- Img - image files
+ | | |
+ | | +-- AltBranding - image files used for 3rd party branding
| | |
- | | +-- Branding - image files used for CodeSnip branding
+ | | +-- Branding - image files used for CodeSnip branding only
| | |
- | | +-- Egg - image files for 'Easter Egg'
+ | | +-- Egg - image files for 'Easter Egg'
| |
- | +-- Misc - other resources
+ | +-- Misc - other resources
| |
- | +-- Scripts - scripting files
+ | +-- Scripts - scripting files
| |
- | +-- 3rdParty - 3rd party scripting files
+ | +-- 3rdParty - 3rd party scripting files
|
- +-- Tests - contains test code
+ +-- Tests - contains test code
|
- +-- Src - test source code
+ +-- Src - test source code
|
- +-- DUnit - test source code that uses the DUnit framework
+ +-- DUnit - test source code that uses the DUnit framework
- If, by chance you also have Bin, Exe and / or
- Release directories don't worry - all will become clear.
+ If, by chance you also have a _build directory don't worry - all will become clear.
Git users may also see the usual .git hidden
directory. If you have done some editing in the Delphi IDE you may also see
occasional hidden __history folders.
@@ -491,19 +514,21 @@
./ | - +-- Bin - receives object files for CodeSnip - | - ... - | - +-- Exe - receives executable code and compiled help file - | - +-- Release - receives release files + +-- _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 | ...
- If the Bin folder already existed, it will have been emptied.
- In addition, Make will have created a .cfg file from
+ If the _build/bin folder already existed, it will have been emptied.
+ In addition, Make will have created a .cfg file from a
template in the Src folder. This .cfg file is needed
for DCC32 to run correctly. The file will be ignored by Git.
- Each of these options is described below. All except the last assume that
+ Each of these options is described below. All except options 5 and 6 assume that
Make config has been run.
The CodeSnip executable, named CodeSnip.exe will be
- placed in the Exe folder.
+ placed in the _build\exe folder.
> Make -DPORTABLE codesnip
- Again the executable is placed in the Exe folder, but this time
+ Again the executable is placed in the _build\exe folder, but this time
it is named CodeSnip-p.exe
> Make help
+
+ The compiled help file will be written to the _build\exe folder.
+
+ The same help file is used for the standard and portable editions. +
+
- The setup program requires that the CodeSnip excutable and the
- compiled help file are already present in the Exe directory.
+ The setup program requires that the CodeSnip executable and the
+ compiled help file are already present in the _build\exe directory.
@@ -672,7 +705,7 @@
The setup program is named CodeSnip-Setup-x.x.x.exe, where
x.x.x is the version number extracted from CodeSnip's version
- information. It is placed in the Exe directory.
+ information. It is placed in the _build\exe directory.
@@ -697,6 +730,7 @@
Make can create zip files containing all the files that are included in a release.
+ Zip files are written to the _build\release directory.
- The release file for the standard edition of CodeSnip includes the
- setup file along with ReadMe.txt from the Docs
- directory. Both files must exist.
+ The release zip file for the standard edition requires that the setup files is already
+ present in the _build\exe directory.
+
+ The release file includes the setup file along with ReadMe.txt
+ that is automatically generated from Docs\ReadMe-standard.txt.
@@ -716,22 +754,33 @@
> Make release
- By default the release file is named dd-codesnip.zip. You can
+ By default the release file is named codesnip-exe.zip. You can
change this name by defining the RELEASEFILENAME macro or
enviroment variable. For example, you can name the file
MyRelease.zip by doing:
> Make -DRELEASEFILENAME=MyRelease.zip release
+> Make -DRELEASEFILENAME=MyRelease release
+
+
+ Note that the .zip extension should not be included in the file name.
+
- The release file for the portable edition includes the portable executable
- file, CodeSnip-p.exe, the help file CodeSnip.chm and
- several files from the Docs directory. All must be present.
+ The release zip file for the portable edition cannot be created until the
+ CodeSnip excutable and the compiled help file are already present in the
+ _build\exe directory.
+
+ The release file includes the portable executable file, CodeSnip-p.exe,
+ the help file CodeSnip.chm, Docs\License.html and
+ ReadMe.txt that is automatically generated from
+ Docs\ReadMe-portable.txt.
@@ -747,7 +796,11 @@
MyPortableRelease.zip by doing:
-> Make -DPORTABLE -DRELEASEFILENAME=MyPortableRelease.zip release
+> Make -DPORTABLE -DRELEASEFILENAME=MyPortableRelease release
+
+
+ Once again note that the .zip extension should not be included in the file name.
+
Warning: If you are building both the standard and portable @@ -756,6 +809,35 @@
+ A version number can be suffixed to the release zip file name by defining the VERSION macro.
+ This macro works with both the PORTABLE and RELEASEFILENAME macros.
+
+ 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: +
+ +> Make -DVERSION=4.22.0 release
+
+
+ This will create a zip file named codesnip-exe-4.22.0.zip.
+
+ A more complex example would be to append the same version number to a portable edition build named MyPortableRelease. Do:
+
> Make -DPORTABLE -DRELEASEFILENAME=MyPortableRelease -DVERSION=4.22.0 release
+
+
+ This time the resulting zip file will be named MyPortableRelease-4.22.0.zip.
+
To perform a complete build of the portable edition of CodeSnip do
> Make -DPORTABLE
+
+ Note that the RELEASEFILENAME and VERSION macros that can be used for customising
+ zip file names can be used here too.
+
+ 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 +
+ +> Deploy 9.9.9
+
+
+ where 9.9.9 is the release version number.
+
+ 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. +
+ +
+ Using Deploy 9.9.9 is the equivalent of doing:
+
> cd Src +> Make -DVERSION=9.9.9 +> Make -DPORTABLE -DVERSION=9.9.9 +> cd ..+
- To compile the tests, open the .\Src\CodeSnip.groupproj group
+ To compile the tests, open the Src\CodeSnip.groupproj group
project file in the Delphi XE IDE. Now select the CodeSnipTests.exe
target in the project manager and compile.
If they were not already present Bin and Exe
- sub-directories will have been created in the .\Tests directory.
+ sub-directories will have been created in the Tests directory.
The Exe directory contains the DUnit test program while
Bin contains intermediate binaries.
You can compile the tests as either a GUI application (default) or as a
console application. For details please see the comments in
- .\Tests\Src\DUnit\CodeSnipTests.dpr.
+ Tests\Src\DUnit\CodeSnipTests.dpr.
+ If you are intending to release your own application based on the CodeSnip source code you must either change the source code as described below or seek written permission to use the DelphiDabbler CodeSnip branding. To seek such permission please use the CodeSnip Issue Tracker on GitHub. +
+ ++ 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 must: +
+ +
+ Replace the files in the Src\Res\Img\Branding directory with copies of the identically named placeholder files in the Src\Res\Img\AltBranding 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 Src\Res\Img\Branding without copying the placeholder files across then CodeSnip will fail to build.
+
+ 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: +
+%ProgramData% and %AppData% sub-directories.
+
+ Provide your own license file with content compatible with the requirements of the CodeSnip license as it relates to the code reused from the CodeSnip source tree. Do not edit or re-use Docs/License.html.
+
+ Modify source code and documentation where necessary to acknowledge the origins of the program's source code, documentation and images, in accordance with the CodeSnip license. +
+
+ Note that the CodeSnip license can be found in Docs\License.html.
+
+ If you are unsure about whether your changes meet the license requirements then you can seek clarification by creating an issue on the aforementioned Issue Tracker. +
+