[Top] [Prev] [Next] [Bottom]

Chapter 2: SDE System, Product and Project Structure

2.1 SDE System

An SDE system consists of files that together implement a function of some kind. A system can either include a complete function, like for example a Process Station, or a sub-function like an I/O driver in the operating system.

An SDE system includes source code, object code, documentation, etc, including mechanisms for its building. The files that are not created by building procedures are version-controlled, i.e. different versions of source files are saved in a system.

A system is defined as a hierarchical structure. System root directories are placed in a directory pointed to by the SDE_SYSTEMS environment variable. If the variable is omitted the directory /ipa/systems is used. A system contains one or several configurations, where a system configuration is a system version. A configuration consists of a tree structure of subsystems. A subsystem usually collects files that make a logical (sub)function of the system.

During the development cycle, some new functions may be added to a system and then new subsystems can be added in the current configuration. For this reason different configurations may have a different structure. Figure 2-1 shows the logical structure of a system.

Fig 2.1 System Structure

Each subsystem contains an RCS1 library. The components of a system (the files) are stored in RCS libraries as versioned files. Each versioned file stored in an RCS library may contain several versions of the file. Particular versions of files may be checked out and used for system building.

Physically, only one RCS directory exists for each subsystem. In new configurations, the RCS directories are specified as symbolic links to the RCS directories for the first configuration. (Figure 2-2).

Fig 2.2 System structure

2.1.1 Versioned Files

SDE-CORE uses RCS for storing files in the RCS libraries (directories). A RCS library is a Unix directory that contains versioned files. From a Unix point of view, a versioned file is a standard Unix file which may be manipulated by any Unix command. Such a file, however contains several versions of a file. SDE-CORE commands based on RCS commands (or directly RCS commands) can extract (check out) a specific version of a file from a versioned file. A versioned file has the suffix ,v.

Figure 2-3 shows a logical structure of a versioned file stored in an RCS library.

Fig 2.3 A structure of a versioned file

A file version is defined by the following attributes:

2.1.2 Change Request

Change Request (CR) is a concept known in Version Management. It is based on a principle that all changes made in a system are registered and described as logical changes of system functions. Change Requests collect all requirements for changes and provide information about what actual changes have been done due to the requirements.

A Change Request includes the following information:

2.2 SDE Product

A product is an extract from one or several systems, in a form suiMETA for distribution, installation and user access. It can be either an end-user product containing programs or an internal product consisting of libraries and definition (include) files to be used by other programmers. Any type of files, including documentation, may be part of a product.

A product is defined by a name and by a release number2. A release may be a major release (not backwards compatible), a minor release (added functionality), or a revision (bug fixes). When specifying the development phase of a product, a release may be defined as a pre-release, an alpha release, or a beta release. The product name format used in product manuals is the following:

Product*X.Y/Z Example: SDE*2.2/0
Product*X.Y/ZPn Example: SDE*2.1P/0 (Pre-release 1)
Product*X.Y/ZAn Example: SDE*2.2/A1 (Alpha- revision1)

SDE defines release number in the following format:


The "/" character is replaced by "-" character, because the "/" character has a special meaning in the Unix file system.

An SDE product includes files placed in a directory structure. The top directory of this structure is called the product root. All product roots are located in a common product directory which is defined by the SDE_PRODUCTS environment variable. If the variable is omitted, the /ipa/products directory is used. This directory contains SDE products or links pointing to them. Each product root directory contain release directories which in turn include subdirectories and files. All files of a product must be placed under a release directory. The structure of a product release directory tree depends on the product.

Figure 2-4 shows an example of a product structure containing an SDE product:

Fig 2.4 Product Structure

A product can be managed by the SDE-Product Manager application, or by the line command product. There are also some other commands that are used for product creation, delivery, etc.

2.2.1 Products Available for Several Platforms

Some SDE products can be developed for different platforms. In that case the product is divided in different platform (or target) releases. The SDE structure looks as shown in Figure 2-5.

Fig 2.5 Product Structure for different platforms

Note that it is not necessary that all platforms have the same product versions. It may happen that a revision is required for one platform, but not for others. In that case only one revision need to be made. SDE commands define platform-dependent products in the following way:

product/target/version; product is a product name, target/version is the release name

2.3 SDE Project

All development and maintenance work is done within the frame of a project. The goal of a project is to develop, enhance, or modify one or several systems and produce new versions of products. An SDE project defines a common working structure for programmers defined as project members. It also includes references to the systems that are supposed to be changed during the development/maintenance process. Finally, the SDE project includes common definitions specific for the project.

Note that an SDE project does not describe how a product is produced. All information needed for the product generation is stored in SDE systems. An SDE project is a temporary structure that may be removed when the project work is finished.

Figure 2-6 shows relations between projects, systems and products. System A and System B are modified in the project P. Product X (and possibly other products) are generated from the systems A and B. Systems A and B refer to external components, other SDE products and SDE systems, i.e. these components are used in the building process of the systems A and B.

Fig 2.6 Project Frame

Each project has its own working structure, but several projects may use the same system, maybe also at the same time. A typical example is to have two projects, one a development project and one a maintenance project where different configurations of the same system are connected to different projects. See Figure 2-7.

Fig 2.7 Two projects share the same system

The project structure starts from the project root directory which is located in a directory pointed to by the SDE_PROJECTS environment variable. If the SDE_PROJECTS variable is omitted then the directory /ipa/projects is used. The /ipa/projects directory collects links to all projects in the file system. Each link points to a home directory for the project. The home directory of a project is defined when the project is created, and it may be placed anywhere in the file system.

The info directory is used for some information files. It contains at least one file called overview. Additional files of similar character may be placed here.

The tools directory is used for some tool procedures related to the project. It contains a script called startup. This script is executed when a project member sets up a project. Initially this script includes a welcome message, but it can be used for project common definitions, as well as for messages to the project members.

The doc directory can be used for project documentation. Note that the whole SDE project is a temporary structure, so you should definitely not save here your documents that are not of temporary character.

The systems directory contains symbolic links to all the systems connected to the project. Note that systems are not placed directly in the project, but only referred to from the project.

The members directory includes working directories of the project members. Each project member works in his/her directory or in subdirectories related to the systems. Each member may have a script called startup for his/her own definitions for the project. This script is executed after the common startup script.

The SDE-Project Manager application is used for managing projects. It includes functions for project creation, adding members to a project, connecting systems to a project, setting up a project, etc. Alternatively the line command project can be used.

2.4 Relations Between Systems, Projects and Products

In the most simple case a product consists of a subset of the files present and generated in one single system. In this case the most natural is that system configurations follow product versions (releases). For example, when the development of a product PRODUCT*2.1/0 starts, the new system configuration called 2.1-0 is created.

For pre-releases that can be created several times in a short period, and that will not be maintained, but replaced by a new pre-release, it is not necessary to create a new system configuration. It is sufficient to mark the file versions used for pre-release creation with a symbolic name that corresponds to the product release. Of course, a new product version structure must be created for the product release.

If a product is more complex, then it will probably be created from several systems. In order to put together different configuration of systems, it is a good idea to have a system that is directly related to the product. Each configuration of such a system (we may call it the "product system"), corresponds to a product version. A product system contains information about which configurations of other systems are used for the product release. This information is stored in a top-level product definition file (a pd file). The top-level pd file should point to pd files from configurations of other systems via #include statements.

A project can connect one or several systems. Project members have separate working directories for each system under their project home directories.

It is not necessary to have a one-to-one relation between projects and products. From a project several products may be created. In some cases several variants of the same product may be created from the same project.

When a system is connected to a project it is possible to define to which level in the system structure the connection will be made. The top level of the connection determines to which level programmers can reach files from the systems.

If a whole system is connected (added) to the project, programmers may select any configuration of the system to work with. It may happen that someone works in a wrong configuration!

If a system configuration is connected to a project, then it is possible to work only within one configuration. This is more secure, but each time a new system configuration is created, a new project must be created too. This can be time consuming, if programmers have their own temporary files, help files, or other files in the project.

It is possible to manage a situation where a project points all the time to a "work" configuration, and the "work" configuration always denotes the latest configuration - used for the current development or maintenance (see Section 3.2.1).

[Top] [Prev] [Next] [Bottom]

1 Revision Control System

2 The new standard names within ABB Automation and Drives are somewhat different than in SDE:

An SDE product corresponds to a Component or to a Function. A release corresponds to a version.