Source Code Repo Structure

These notes apply to the parsnip branch of the CodeSnip SVN repo and explain
the design of the directory structure.

At present the parsnip repo is quite messy - that's because I'm slowly
changing it over to a new structure, and for reasons of not wanting to clobber
the merging of changes from the repo trunk, I can't do it all in one go.

This document presents the new structure I'm aiming at, lists the original
structure, still used in trunk, and shows both how I'm proposing to change
over without breaking too much at once and how far I've got (see: Process for
Converting to New Directory Structure below).

The new structure should be in place in the parsnip branch by before the end
of the early development of CodeSnip 5.

New Directory Structure

The code committed to the SVN repo will ultimately have this structure:

Docs
  ChangeLogs
  Design
    FileFormats
Src
  Common
  Help
    CSS
    HTML
    Images
  Install
    Assets
  Lib
    DDabLib
    DelphiColl
    SynEdit
  Main
    AutoGen
    Assets
      CSS
      HTML
      Img
        Branding
        Egg
      Misc
      Scripts
        Import
    Import
  Portable
  Tests
    DUnit

In addition to Docs and Src top level directories there will also be a
Build directory that stores files output by the build process. This directory
will not be included in SVN. The structure of Build is:

Build
  Dist
   Standard
    Portable
  Exe
    Tests
  Obj
    Lib
      DDabLib
      DelphiColl
      SynEdit
    Main
    Portable
    Tests
      DUnit

Description

The directories have the following purposes:

• Docs

  Contains the program's documentation, excluding help, which is included in
  Src\Help.

  Some of the files in this folder are included in releases, but most are not.

  • Docs\ChangeLogs

    Contains a change log for each major release of CodeSnip.

  • Docs\Design & Docs\Design\FileFormats

    Various documents explaining the design of the program.

• Src

  All of CodeSnip's source code, with the exception of the Delphi VCL and the
  Indy components, is stored in the Src folder and its sub-folders.

  The only files stored directly in Src will be makefiles, project group
  files and license files. The remaining source is grouped into sub-projects,
  each stored in its own sub-folder of Src. These sub-projects are:

  • Src\Help

    The project's HTML help file. It stores project files in the root.
    Content is divided amongst its sub-folders.

    • Src\Help\CSS

      Contains the help project's CSS style sheets

    • Src\Help\HTML

      Contains the help topic files.

    • Src\Help\Images

      Contains image files used in the help file.

  • Src\Install

    Source files for generating CodeSnip's set-up program. Contains the
    Inno Setup project file and associated Pascal Script files.

    • Src\Install\Assets

      Contains any assets to be compiled into the set-up program.

  • Src\Lib

    Source code of various libraries imported from 3rd party sources that
    are required to build CodeSnip. This folder contains only files that
    related to all the library. Each library has its own sub-directory,
    named appropriately.

    • Src\Lib\DDabLib

      Source code from the DelphiDabbler Code Library project.

    • Src\Lib\DelphiColl

      Source code from the Delphi Collections library.

    • Src\Lib\SynEdit

      Source code from the SynEdit project.

  • Src\Main

    Source code of the main CodeSnip application. All Pascal source code and
    associated project / make files are stored in this directory.

    • Src\Main\AutoGen

      Contains any intermediate files generated by the makefile along with
      a read-me and license files.

      Only the read-me and license files are recorded in SVN. Generated
      files are not since they can be regenerated from the makefile at
      will.

    • Src\Main\Assets

      Container for any assets, including scripts, that are to be included
      in the program's resources. This directory does not contain any
      files: all the files are contained in sub-directories.

      • Src\Main\Assets\CSS

        Style sheets for HTML displayed or generated by the program.

      • Src\Main\Assets\HTML

        HTML files the are displayed in the program's UI.

      • Src\Main\Assets\Img, Src\Main\Assets\Img\Branding &
        Src\Main\Assets\Img\Egg

        Stores any images that are embedded in the program's resources.
        General images are in Img while Branding contains restricted
        images relating to the program's branding and Egg contains
        images used by the program's Easter Egg.

      • Src\Main\Assets\Misc

        Contains any assets that don't fit into the other Assets
        sub-directories.

      • Src\Main\Assets\Scripts and Src\Main\Assets\Scripts\Import

        Contains scripts that are executed from within HTML display in
        the program. The Import sub-directory contains scripts
        imported from 3rd party sources.

    • Src\Main\Import

      Contains source files referenced directly in CodeSnip's project
      file that have been imported from other sources.

      Note: Other imported source code that is not referenced in
      CodeSnip's project file is included in the main Src\Lib directory.

  • Src\Portable

    Contains the source code of the CodeSnip Portable launcher program.

  • Src\Tests

    Contains various test projects, each in its own sub-directory.

    • Src\Tests\DUnit

      Contains all DUnit tests

  In addition, there is the following directory (which may or may not be
  required).

  • Src\Common

    To be used to store any files used by more than one sub-project.

    This directory could have sub-directories similar to those in Src\Main
    if required.

    At present there are no common files that would not be stored directly
    in Src, so this directory could be omitted.

• Build

  Contains all files that result from building the project's source code.

  • Build\Dist

    Contains sub-directories that accumulate the files that are to be
    included in each distribution.

    • Build\Dist\Standard

      Contains files to be included in the standard distribution.

    • Build\Dist\Portable

      Contains files to be included in the portable distribution.

  • Build\Exe

    Contains all distributable executable files that result from various
    compilations. These include the CodeSnip and CodeSnipPortable loader
    executables, set-up program and help file.

    • Build\Exe\Tests

    Contains executable files compiled from test suites that are not for
    distribution.

  • Build\Obj

    Contains sub-directories that receive intermediate binary (object) files
    generated by compilers.

    • Build\Obj\Lib

      Contains sub-directories that receive binary intermediate files for
      the various libraries.

      • Build\Obj\Lib\DDabLib

        Contains binary files for the DelphiDabbler Code Library
        project.

      • Build\Obj\Lib\DelphiColl

        Contains binary files for the Delphi Collections project.

      • Build\Obj\Lib\SynEdit

        Contains binary files for the SynEdit project.

    • Build\Obj\Main

      Contains binary files for the main CodeSnip project.

    • Build\Obj\Portable

      Contains binary files for the CodeSnip Portable launcher.

    • Build\Obj\Tests

      Contains sub-directories that contain binary files resulting from
      test compilations.

      • Build\Test\DUnits

      Contains binaries resulting from compilation of DUnit tests.

Process for Converting to New Directory Structure

Build Directory

The Build directory structure is entirely new and replaces the Bin, Exe
and Release directories in the old structure.

Make files, .cfg and Delphi project files will be updated over time to store
binary files into the new Build directory over time. This process can proceed
at any time since the affected folders are not part of SVN and non consideration
of merges has to take place.

Docs Directory

The Docs directory remains unchanged in moving to the new structure.

Src Directory

Migration from the old structure to the new is complicated by the need to merge
changes from SVN trunk into the parsnip code tree.

This means that, while the need to perform such merges continues, it is
difficult to make all the changes. Only when the divergence between parsnip
and trunk becomes so great that future merges are too problematic can the
final transition be made.

The current structure of Src in parsnip is as follows:

Src
  3rdParty
  AutoGen
  Help
    CSS
    HTML
    Images
  Install
    Assets
  Lib
    3rdParty
      DDabLib
      DelphiColl
      SynEdit
  Portable
  Res
    CSS
    HTML
    Img
      Branding
      Egg
    Misc
    Scripts
      3rdParty

In addition there is a Test top level sub-directory with the following
structure:

Test
  Bin
  Exe
  Src
    DUnit

Of these directories Test\Bin and Test\Exe are excluded from SVN.

Action required

To complete the migration the following tasks need to be performed on the old
source tree:

• Src

  Ideally a new Main sub-directory would be created in Src and all
  CodeSnip files would be moved from Src into Main, leaving behind files
  that continue to belong in Src.

  Since Src is affected by merges from trunk a staged approach is needed:

  • Create new Main sub-directory.

  • Move existing files created in parsnip since it was branched from
    trunk into Src\Main, updating project files as required.

  • Add any new CodeSnip project files directly into Src\Main instead of
    Src.

  • When merging from trunk has ceased do the following:

    • Move remaining CodeSnip files from Src to Src\Main. Be careful
      to leave behind files that actually belong in Src such as the group
      project file, make file etc.

    • Update relevant project files as required.

• Src\3rdParty

  Ideally this directory and its contents would be renamed and moved into
  Src\Main\Import.

  Since Src\3rdParty is affected by merges from trunk a staged approach is
  needed:

  • Create a new Src\Main\Import directory.

  • If and when any new code is imported into CodeSnip in parsnip that isn't
    also imported into trunk add it directly to Src\Main\Import.

  • When merging from trunk has ceased do the following:

    • Move any remaining files from Src\3rdParty to Src\Main\Import.

    • Delete Src\3rdParty, which should now be empty.

    • Update any relevant project and make files as required.

• Src\AutoGen

  Ideally this directory and its contents would be moved into Src\Main.

  Since Src\3rdParty is affected by merges from trunk a staged approach is
  needed.

  Given that it's only the LICENSE and ReadMe.txt files in Src\AutoGen
  that are affected by merges (because auto-generated files are ignored by
  SVN), the following approach should work:

  • Create a new Src\Main\AutoGen directory.

  • Adjust make files to store auto-generated files in the new directory.

  • Adjust search paths etc to find the auto-generated files in their new
    location.

  • When merging from trunk has ceased do the following:

    • Move any remaining files from Src\AutoGen to Src\Main\AutoGen.

    • Delete Src\AutoGen, which should now be empty.

    • Update any relevant project and make files as required

• Src\Help and sub-directories

  These directories do not need to be moved or changed.

  They are affected by merges from trunk, so do not rename any
  directories until merges have ceased.

• Src\Install and sub-directories

  These directories do not need to be moved or changed.

  They are affected by merges from trunk, so do not rename any
  directories.

• Src\Lib and sub-directories

  Src\Lib changes only in that the 3rdParty directory is removed.

  Since Src\Lib was added to the parsnip branch after it branched from
  trunk the directory is not affected by merges from trunk and so the
  changes can be carried out at any time.

  The following changed are needed:

  • Move all sub-directories of Src\Lib\3rdParty into Src\Lib, e.g.
    Src\Lib\3rdParty\DDabLib moves to Src\Lib\DDabLib.

  • Delete the now empty Src\Lib\3rdParty.

  • Adjust the library project files and makefile re the new locations.

• Src\Portable

  This directory does not need to be moved or changed.

  Src\Portable was added to parsnip after it was branched from trunk so
  the directory is not affected by any merges from trunk.

• Src\Res and its sub-directories

  Ideally this directory and its contents would be renamed and moved to
  Src\Main\Assets.

  All sub-directories would retain the names and relative structure except
  Src\Res\Scripts\Import which would be renamed as
  Src\Main\Assets\Scripts\Import.

  Since Src\Res is affected by merges from trunk a staged approach is
  needed:

  • Create the new Assets directory structure in Src\Main.

  • If and when any new assets are added to the project, add them to the
    appropriate sub-directory of Src\Assets instead of Src\Res.

  • When merging from trunk has ceased proceed as follows as follows:

    • Move files from Src\Res\Scripts\3rdParty into
      Src\Assets\Scripts\Import.

    • Move files from the remaining sub-directories of Src\Res into the
      correspondingly named sub-directories of Src\Assets.

    • Delete Src\Res and all the sub-directories, which should now be
      empty.

    • Update any referencing project files and makefiles.

• Test and its sub-directories.

  Ideally, a new Src\Test directory should be created and the
  Test\Src\DUnit directory and contents should be moved into Src\Test,
  creating a new Src\Test\DUnit directory. Then _Test should be deleted.

  Since Test is affected by merges from trunk as staged approach is
  required:

  • Create a new Src\Test directory.

  • Continue to add new unit tests to the existing Test directory until
    merging from trunk ceases.

  • Create any new, non-DUnit, test projects as sub-directories of Src\Test.

  • When merging from trunk has ceased do the following:

    • Move the DUnit directory and its contents from Tests\Src into
      Src\Tests, creating a new Tests\Src\DUnit directory.

    • Delete Tests and all its remaining contents.

    • Adjust any project and make files accordingly.

$Date$
$Rev$