Introduction

This document describes Kitto^x's standard conventions for setting up Delphi, and how to change them for custom setups.

Kickstart a new application

For a quick startup of a new application, you can just:

1. Copy the directory structure of HelloKitto or another example application;
2. Open the project file and save it under a new name;
3. Edit Config.yaml and start creating your own metadata files.

---

When running the compiled application, beware that it will try to run as a service if under an administrator account. To force the application to run with a visible GUI, pass -a as a command line argument.

---

If instead you want a detailed description of what's where and what you can customize, read on.

Details

A Kitto^x application is made up of a Delphi project that you create and maintain, a Home folder with metadata and resources (such as images or javascript files), and a link to the Kitto^x sources or precompiled files.

Standard directory layout

As you can see in the HelloKitto example, a typical folder structure for Delphi 10.2 Tokio goes like this:

• HelloKitto
  • Home
    • Metadata
      • Models
      • Views
      • Config.yaml
    • Resources
      • js
        • application.js
    • Example.exe (the compiled application)
  • Source
  • Projects
    • D12
      • HelloKitto.dproj/dpr (project files)
  • Lib
  • Externals
    • Kitto^x
      • Source
      • Home

Your application code goes into Source and Projects, and the project file should be configured to output the compiled dcu files into subdirectories of Lib:

Unit output directory = ..\..\Lib\$(Version)\D12\$(Platform)

and the exe file into Home:

Output directory = ..\..\Home

This folder contains your yaml metadata and support files as well, and is called the Application Home.

The Application Home path

The Application Home is assumed to the your executable's directory. You can change this (for example when using a single Kitto^x executable to serve different applications) in the following ways:

• By passing a -home argument on the command line.
• By setting the property TKConfig.AppHomePath at application startup.

Finding Kitto^x: The System Home path

Externals\KittoX\Home contains the predefined metadata and support files, such as Kitto^x's default style sheet, CSS, JavaScript libraries, SVG icons, and HTML templates, which are used by your Kitto^x application at run time and you shouldn't need to touch. This is called the System Home.

As you can see, the application needs to have Kitto^x inside its directory structure. This is done to allow different applications to use different versions of the library without stepping on each other's toes, and to make the application as much self-contained as possible.

The project should be configured to find Kitto^x, either in source format:

Search path = ..\..\Externals\KittoX\Source;

..\..\Externals\KittoX\Source\EF;

..\..\Externals\KittoX\Source\ThirdParty;

or in pre-compiled format:

Search path = ..\..\Externals\KittoX\Lib\$(Platform)

---

For the latter version to work, you need to build Externals\KittoX\Projects\D13\KittoXCore.dproj at least once.

---

By default, the System Home is the first existing path in the following list (relative to the executable directory):

..\Externals\KittoX\Home\

..\..\ext\KittoX\Home\

..\..\Externals\KittoX\Home\

..\..\..\KittoX\Home\

..\..\..\..\KittoX\Home\

%KITTOX%\Home\

If none of the paths above exists, then the Application Home is assumed. This allows you to prepare a zero-configuration setup in which the System and Application Home paths are merged in the default Application Home.

Setting up a custom System Home

If you'd like a centralized setup better, you can change that easily, in one of the following ways:

1. You can make KittoX a junction/link so it points to a directory elsewhere. Windows has been supporting file system links for a good while now; you can find a utility to manage them here.
2. If you use Subversion or Git, you can define KittoX as an external/submodule that points to a different repository.
3. You can put Kitto^x elsewhere and change the search path accordingly in the project options. Be warned that this takes care of the KittoX\Source directory, but your application will still need KittoX\Home at run time. If you want to move KittoX\Home elsewhere as well, you will need to do the following at application startup (for example, in a unit's initialization section):

TKConfig.SystemHomePath := 'D:\Path\To\KittoX\Home\';

That's it. You should now be ready to develop and test your Kitto^x applications. We suggest that you stick to the standard conventions unless you have good reasons to do otherwise, because they are designed to save you time and effort in the long run.