Creating User Libraries

In its simplest form, a user library is just a normal include file, placed in a different folder.

This will make the contents of the include file available to any file that includes it, but it will not automatically enable the syntax highlighting or autocomplete.

To make an element available for syntax highlighting and auto complete, it must be documented, using comments with special tags.

This is an example of how a define can be documented:

/*
@brief A fixed password
@helpid 10
@helpfile SimpleLib.chm
@menu Simple/Configuration
*/
#DEFINE MAIN_PASSWORD "password"

Tags

@helpid <id>

As a minimum, the comment must contain the tag "helpid", which is followed by a number.

Ideally, the number would be used to find the documentation in the help file. If this tag is not present or 0, the element is not included in the documentation.

@helpfile <path>

The tag "helpfile" provides the path to a .chm file to use as help.

@brief <description>

The tag "brief" must be followed by the description of the function on the same line.

@menu <path>

The "menu" tag adds the element to the User Library Wizard menu. The tag is followed by the path to place the element at, using "/" to create sub-menus. The menus are sorted alphabetically.

@group <number>

The group tag can be used to separate the contents of a menu into sub-groups.

All elements in a menu with the same group number will be grouped together. The groups are sorted numerically based on the number.

@required <condition> [hide]

The required tag is used to place restriction on when an element can be used.

The element can either be removed from the menu or shown as disabled in the menu.

The tag is followed by the name of a condition and optionally the "hide" keyword.

If "hide" is present, the element is removed from the menu if the condition is not met.

The supported conditions are:

	•MATH_DOUBLE	Double math library is enabled
	•MATH_FLOAT	Double math library is disabled
	•MODE_X32	The project is compiled for the X32 architecture
	•MODE_NX32	The project is compiled for the NX32 architecture
	•MODE_NX32L	The project is compiled for the NX32L architecture
	•LSS	Large String Support is enabled.

@deprecated <name of replacement>

This tag can be used to mark an element as deprecated. If "Show legacy functions" is not enabled in the Settings, the element will not be shown.

The tag is followed by an optional name of an element that replaces this element. This name is not currently used.

Naming of elements

Undocumented functions, variables, etc. are still included in the application so make sure to use unique names that do not collide with names used by the application.

To reduce the risk of collision, the names should be prefixed with a long string related to the library name.

The documented elements can use simpler names but care should still be taken to avoid colliding with future names from other libraries, especially if they are to be shared with third parties.

Encrypted libraries

Combining the use of INTERFACE/IMPLEMENTATION with encrypted include files, it is possible possible to distribute encrypted libraries.

Two include files are needed:

The first file must contain the INTERFACE definitions and the documentation.

The second file must contain the IMPLEMENTATION and must be encrypted.

The first file must INCLUDE the encrypted version of the second file.

See the Implementation project in the example library for an example of how this can be done.