Author: FCM team

# FCM: User Guide: A Brief Introduction to the FCM Perl API

The majority of FCM functionalities are provided by a set of Perl modules. Old modules developed prior to release 2-0 reside in the `FCM1::*` name-space. Modules developed thereafter reside in the `FCM::*` name-space. These are sub-divided into the following name-spaces:

`FCM::Class`

  Provides an internal object class framework.

  The majority of the classes in the `FCM::*` name-space are sub-classes of either `FCM::Class::CODE` or `FCM::Class::HASH`. The former creates classes that are blessed `CODE` references, and is intended for configurable functional (i.e. mostly stateless) objects. The latter creates classes that are blessed `HASH` references, and is intended for data objects.

  Note: In theory, we could use the standard module `Class::Struct` or the modern MOOSE framework. The problem is that the former is not powerful enough to give us what we need, and the latter is not a standard module and is too heavy weight for our intends and purposes. Instead, the developer decides that it is easier to go for a light weight and in house solution.

`FCM::CLI`

  Provides the logic and configuration of the command line interface (CLI).

  It is made up of the following components:

  `FCM::CLI`
    Logic to provide help and invoke functions of `FCM::System`.
  `FCM::CLI::Exception`
    CLI exception.
  `FCM::CLI::Parser`
    CLI option parser and configuration.
  `fcm-*.pod`
    Help files for the CLI commands.
`FCM::Context::*`

  Provides the data structures for storing the run time contexts.

  The objects of these classes do very little, but they provide the data structures that define the states of the program at run time.

`FCM::Exception`

  Provides the base class for exceptions.

`FCM::System`

  Provides a façade to the functionalities of the FCM system.

  The actual implementation is delegated to the following:

  `FCM::System::CM`
    The code management system. Currently a thin adapter to `FCM1::Cm`.
  `FCM::System::Misc`
    Miscellaneous functions, e.g. `browse`, `cfg-print`, `keyword-print`.
  `FCM::System::Old`
    Thin adapter to the old extract and build systems.
  `FCM::System::Make`
    The logic of the FCM make system.
  `FCM::System::Make::Build`
    FCM make: build system logic.
  `FCM::System::Make::Build::*`
    FCM make: build system components: File type and task specific logic.
  `FCM::System::Make::Extract`
    FCM make: extract system logic.
  `FCM::System::Make::Mirror`
    FCM make: mirror system logic.
  `FCM::System::Make::Preprocess`
    FCM make: preprocess system logic, actually a configuration of `FCM::System::Make::Build`.
  `FCM::System::Make::Share::*`
    Shared logic between all subsystems in `FCM::System::Make::*`.
`FCM::Util`

  Provides supporting utilities.

  Functionalities include:

  - abstract utilities for SVN URLs and file system paths.
  - configuration file reader.
  - event handler.
  - file utilities.
  - message report.
  - name space utilities.
  - shell invocation.
  - multi-process task runner.
  - timer.

  The logic of the more complex utilities are delegated to modules in the `FCM::Util::*` name space.

Note: The majority of modules in the old `FCM1::*` name space are considered deprecated, with the exception of `FCM1::Cm` and those providing support functionalities for it. The functionalities of these modules will eventually be absorbed into the `FCM::System::CM` framework.