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
        Imports
    Imports
  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
  Distrib
    Standard
    Portable
  Exe
    Release
    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 that 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\Imports

        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\Imports

      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\Distrib

    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 sub-directories that receive executable files created by the
    build process.

    • Build\Exe\Release

      Contains files that are destined for release in one or more of the
      distributions. They 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 the package and related files generated when libraries are
      built.

      • Build\Obj\Lib\DDabLib

        Contains binary files for the DelphiDabbler Code Library
        project, other than package files.

      • Build\Obj\Lib\DelphiColl

        Contains binary files for the Delphi Collections project, other
        than package files.

      • Build\Obj\Lib\SynEdit

        Contains binary files for the SynEdit project, other than
        package files.

    • 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\Obj\Tests\DUnit

      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. 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 structure of Src in parsnip before the restructuring began was 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 was a Test top level sub-directory with the following
structure:

Test
  Bin
  Exe
  Src
    DUnit

Of these directories Test\Bin and Test\Exe were 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:

  • DONE: Create new Main sub-directory.

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

  • IN PROGRESS 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 those files that continue to belong in Src such as
      the group project file, make file etc.

    • Update relevant project files as required.

• Src\3rdParty

  All changes now complete

  The contents of Src\3rdParty were moved into a new Src\Main\Imports
  directory and Src\3rdParty was deleted. Related project files were
  revised. No changes to make files were necessary.

  Warning re merge conflicts: Src\3rdParty was branched from trunk
  so any merges involving changes to the directory will cause a tree conflict,
  because Src\3rdParty has been deleted. Such a conflict should be resolved
  by rejecting the change. If any of the changes to trunk\Src\3rdParty are
  desirable then merge trunk\Src\3rdParty into parsnip\Src\Main\Imports.

• Src\AutoGen

  All changes now complete

  The versioned contents of Src\AutoGen were moved into a new
  Src\Main\AutoGen directory and Src\AutoGen was deleted. Related project
  and make files were revised.

  Warning re merge conflicts: Src\AutoGen was branched from trunk so
  any merges involving changes to the directory will cause a tree conflict,
  because Src\AutoGen has been deleted. Such a conflict should be resolved
  by rejecting the change. If any of the changes to trunk\Src\AutoGen are
  desirable then merge trunk\Src\AutoGen into parsnip\Src\Main\AutoGen.

• 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 until merges have ceased.

• Src\Lib and sub-directories

  All changes now complete

  All sub-directories of Src\Lib\3rdParty were moved up into Src\Lib and
  Src\Lib\3rdParty was deleted.

  This was safe because Src\Lib was added to the parsnip branch after it
  branched from trunk so the directory isn't affected by merges from
  trunk.

• 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\3rdParty which would be renamed as
  Src\Main\Assets\Scripts\Imports.

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

  • DONE: 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, where
    possible.

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

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

    • 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.

  All changes now complete

  The DUnit sub-directory of Tests\Src, along with its contents, was moved
  into a new Src\Tests and Tests and all its content was then deleted.

  Warning re merge conflicts: The Tests directory, and its only
  sub-directory, Tests\Src\DUnit was branched from trunk. Therefore so any
  merges involving changes within the directory will cause a tree conflict
  because Tests has been deleted. Such a conflict should be resolved by
  rejecting the change. If any changes to trunk\Tests\Src\DUnit are
  desirable then merge trunk\Tests\Src\DUnit into parsnip\Src\Tests\DUnit.
  If any other directories have been added to trunk\Tests or
  trunk\Tests\Src then a decision needs to be made as to if or how to
  reflect those changes in parsnip\Src\Tests

$Date$
$Rev$