U++ package file format
All the information about packages is stored in a text file with the same name as the package and .upp extension. This file stores list of files that belong into the package and also all the settings that are set in Package organizer. This article aims to document the syntax of the .upp file.
Each section of .upp file begins with a keyword and ends with semicolon. The recognized section keywords are:
acceptflags
charset
custom
description
|
file
flags
include
library
|
link
optimize_size
optimize_speed
options
|
mainconfig
noblitz
target
uses
|
|
Accepted flags
Each package can specify a list of flags that it can use to provide special or optimized functionality. Such flags can be then passed with dot prefix and will be only applied to main package and all packages that list it among the accepted flags. This provides a way how to minimize the number of packages that need to be rebuilt when the flags are changed.
Syntax:
|
acceptflags <flag_name> [,<flagname>]*;
|
Example:
|
acceptflags NOGTK, GUI;
|
|
Encoding
The default encoding for all the files in the package can be specified using charset keyword.
Syntax:
|
charset <charset_name>;
|
Example:
|
charset "UTF-8";
|
|
Custom build steps
Each package can invoke so called "custom build steps" which are invoked either at compile time on all file with given extension or when linking, if the extension is one of the special values pre-link or post-link. The build step consists of command to execute and specification of output files, which might be further processed by TheIDE. This can be used for example to generate sources on the fly or to apply some post-processing on the final executables. The command and output may contain a number of variables enclosed in '$(...)' that are replaced upon evaluation:
|
FILE
|
current file name
|
TITLE
|
current file name without extension
|
PATH
|
current file path
|
RELPATH
|
relative path to current file
|
FILEDIR
|
current file directory
|
DIR
|
package directory
|
PACKAGE
|
package name
|
OUTDIR
|
package output directory
|
INCLUDE
|
list of all include paths
|
EXEPATH
|
executable path
|
EXEDIR
|
executable directory
|
EXEFILE
|
executable file name
|
EXETITLE
|
executable file name without extension
|
|
|
Syntax:
|
custom(<when>) <extension>, <command>, <output>;
|
Example:
|
custom ".rc", "rc /fo$(OUTDIR)\\$(TITLE)_rc.obj $(PATH)", "$(OUTDIR)\\$(TITLE)_rc.obj";
custom(POSIX PROTECT) "post-link", "ProtectEncrypt $(OUTPATH) AABBCCDDEEFF00112233445566778899", "";
|
|
Description
Description of package as it appears in Package selection dialogs is set using the description keyword. The description string can also include formatting portion, that determines the color and style of the package name in the package list in TheIDE.
Syntax:
|
description <description_string>;
where
<description_string> = <actual_description> [\377 [B] [I] [<R>,<G>,<B>]]
B makes the text bold
I makes the text italic
<R>,<G>,<B> are integers in range from 0 to 255 specifying the color
|
Example:
|
description "Non-GUI code. Streams, NTL containers, concrete types, Value, XML, C parsing etc...\377B128,0,0";
|
|
Files
Possibly the most important part of package is the list of files that belong to it. Each file in the list can have set several options which specify how it is handled and displayed.
Syntax:
|
file <file_name> [<file_options>]* [,<file_name> [<file_options>]*]*;
where
<file_options> = options(<when>) <option> | depends(<when>) <dependency> | optimize_speed | optimize_size | readonly | separator | charset <charset_name> | tabsize <num 1-20> | font <num 0-3> | highlight <highlighter_name>
|
Example:
|
file
FindInFiles.cpp optimize_speed,
idefile.cpp charset "iso8859-1",
Resources readonly separator,
ide.rc depends() ide.ico;
|
|
File options have following meaning:
options
|
Additional compiler options to be used for file.
|
depends
|
Additional dependency on other file in package. Note that header file dependencies are resolved by build system.
|
optimize_speed
|
In optimal build mode, this file should be optimized for speed.
|
optimize_size
|
In optimal build mode, this file should be optimized for size, even if whole package is optimized for speed. Note that size optimization is default.
|
readonly
|
IDE setting: file should be opened in read-only mode in editor.
|
charset
|
IDE setting: Information about character encoding of file.
|
tabsize
|
IDE setting: Information about tab size.
|
font
|
IDE setting: Information about font used.
|
highlight
|
IDE setting: Information about syntax highlighting overried (normal default depends on file extension).
|
|
Add/Remove flags
It is possible to automatically add or remove flags, based on other flags. This is can be handy for example for platform dependent flag switching.
Syntax:
|
flags(<when>) [!]<flag_name> [[!]<flag_name>]*;
|
Example:
|
flags(POSIX) "ALSA OSS";
|
|
Additional includes
If the package requires some special include paths, they can be added using include keyword.
Syntax:
|
include[(<when>)] <path> [, <path>]*;
|
Example:
|
include ../lib;
include(POSIX) /opt/someapp/include;
|
|
Libraries
If the package requires to be linked with a shared or static library, those can be added using library keyword.
Syntax:
|
library[(<when>)] <lib_name> [, <lib_name>]*;
|
Example:
|
library png;
include(POSIX) jpeg;
|
|
Linking options
Each package can specify special options to be passed to the linker command. Note that since each platform can have different linker, you should provide link option for each supported platform.
Syntax:
|
link[(<when>)] <lib_name> [, <lib_name>]*;
|
Example:
|
link(MSC DEBUG) /nodefaultlib:msvcrt.lib;
|
|
Size optimization
The optimize_size keyword can be used to tell compiler that the entire package should be optimized for smaller size of resulting binary when compiled with "Optimal" settings. It takes no parameters.
Syntax:
|
optimize_size;
|
Example:
|
optimize_size;
|
|
Speed optimization
The optimize_speed keyword can be used to tell compiler that the entire package should be optimized for faster execution when compiled with "Optimal" settings. . It takes no parameters.
Syntax:
|
optimize_speed;
|
Example:
|
optimize_speed;
|
|
Compiler options
Any special options necessary for the package compilation may be added with options keyword. They will be passed to the compiler command only when compiling given package.
Syntax:
|
options[(<when>)] <lib_name> [, <lib_name>]*;
|
Example:
|
options(MSC) "/D PSAPI_VERSION=1";
|
|
Main configuration
The set of flags that are available in the Main configuration droplist in TheIDE are stored using the mainconfig keyword. The name part is optional - if the flags combination doesn't have a name it is represented as an empty string.
Syntax:
|
mainconfig <name> = <flags> [,<name> = <flags>]*;
|
Example:
|
mainconfig "" = "GUI", "Without gtk" = ".NOGTK GUI";
|
|
No BLITZ
The noblitz keyword allows to prohibit BLITZ for entire package. It takes no parameters.
Syntax:
|
noblitz;
|
Example:
|
noblitz;
|
|
Target
The section target can specify the name and/or path to the resulting executable. The value can optionally depend on the flags used.
Syntax:
|
target[(<when>)] <package_name> [, <package_name>]*;
|
Example:
|
target calc.ocx;
target(TEST) ld-test.exe;
|
|
Used packages
Each package specifies a list of packages which it depends on. The dependency specified in uses section can be either conditional (based on flags) or unconditional.
Syntax:
|
uses[(<when>)] <package_name> [, <package_name>]*;
|
Example:
|
uses CtrlCore;
uses(POSIX | LINUX | FREEBSD) PdfDraw;
|
|
|
