# Messages

- What is the MESSAGE system?
- What is the syntax of module.messages file?
- What happens if the same message exist in several modules?
- hardcore has a lot of messages, do they belong there?
- What do I need to include to get the `OpMessage` enum?
- How do I change or introduce a message in different mainline configurations

## What is the MESSAGE system?

The message system is intended to collect all required messages from all modules and put them in one enum, `OpMessage`. Messages can be added by all modules listed in readme.txt in the folders modules/, adjunct/ and platforms/. The messages are read from the file module.messages if present in the module root.

## What is the syntax of module.messages file?

    MSG_NAME				message-owner

    	Description text.

    	Depends on: list of features, defines

message-owner
  The message owner is the name of the developer responsible for the message. Mandatory.
Description
  Text describing the message. Can span several lines. Mandatory.
Depends on
  List of features and defines which this message depends on. The features and defines must be turned on for this message to be visible. The items are separated by "," and/or "and". "nothing" is a valid value. Not mandatory, if left out it means "nothing".

Example:

    MSG_ES_RUN							jl

    	Runs the ecmascript scheduler.

    	Depends on: FEATURE_ECMASCRIPT

This will cause the following to be added to the `OpMessage` enum:

    	enum OpMessage
    	{
    		MSG_NO_MESSAGE,
    		...
    		...
    #ifdef FEATURE_ECMASCRIPT == YES
    		,MSG_ES_RUN
    #endif // FEATURE_ECMASCRIPT == YES
    	};

## What happens if the same message exist in several modules?

A merge of the dependencies is performed. The result is one message with the dependencies from the modules OR:ed together.

## hardcore has a lot of messages, do they belong there?

No, most shall be moved out to the modules where they belong. This can be done without having to change both module.message files at one time.

## What do I need to include to get the `OpMessage` enum?

Nothing, the message file (modules/hardcore/mh/generated_messages.h) is included by core/pch.h.

## How do I change or introduce a message in different mainline configurations

The build-system can be told compile the "current" or "next" mainline configuration. Each mainline configuration has an associated version number. If the setup script finds the file `module.messages.version`, it parses that file instead of the `module.messages`. Thus a message can be added or changed for only one mainline configuration.

It is recommended to only keep the versiond file `module.messages.version` for the "current" mainline configuration and use the default file for the "next" mainline configuration. Thus on switching the mainline version numbers, the versioned file can be removed and only the not-versioned file remains.

Example: If the "current" mainline version is 2.3 and the "next" mainline version is 2.4, and one module needs to use different dependencis for one message on different mainline configurations, it can use two files:

`module.messages.2.3`
  defines all messages for the "current" = 2.3 mainline configuration.
`module.messages`
  defines all messages for the "next" = 2.4 mainline configuration.

So if you want to add or change a message for the "next" mainline configuration, look for the version number of the "current" mainline configuration in `modules/hardcore/version.ini`. If the file `module.messages.current_version` exists, you can edit `module.messages`.
Otherwise copy `module.messages` to `module.messages.current_version`, add it to the repository and modify `module.messages`. Thus the "current" mainline configuration remains unchanged.

The same applies if you want to add or change a message for the "current" mainline configuration: look for the version number of the "current" mainline configuration in `modules/hardcore/version.ini`. If the file `module.messages.current_version` exists, you can edit it
Otherwise copy `module.messages` to `module.messages.current_version`, add it to the repository and modify it. Thus the "next" mainline configuration remains unchanged.