33dadcd154
* minimized TCmdLineLayoutInfo class public section; * updated the TCmdLineScrollBoxControl loader to use %%other switch; using hash list to check of used/unused controls; * updated readme.txt description for UI layout controls; * updated IDE package to make the dialog look close to the existing compiler options; * updated testguibuild to be able to load a certain section only; * added smaller sample files for testguibuild, modified conf.coptui to have %%other switch, where all "non-default" compiler options would go; git-svn-id: https://svn.code.sf.net/p/lazarus-ccr/svn@2806 8e941d3f-bd1b-0410-a28a-d453659cc2b4
182 lines
8.6 KiB
Plaintext
182 lines
8.6 KiB
Plaintext
Command Line Configuration
|
|
|
|
== Source files ==
|
|
|
|
cmdlinecfg.pas - the core unit defining the primary class for configuration
|
|
cmdlinecfgutils.pas - utility functions
|
|
cmdlinecfgparser.pas - the unit for parsing input strings into command lines
|
|
and mapping them to classes of cmdlinecfg.
|
|
cmdlinecfgjson.pas - the json format reader of command-line configurations
|
|
|
|
=== User Interface ===
|
|
|
|
cmdlinecfgui.pas - core unit for UI controller of command-line options
|
|
cmdlinecfguijson.pas - json read of UI controller info.
|
|
cmdlinelclctrlsbox.pas - LCL-based consols list UI controller
|
|
cmdlinelclpropgrid.pas - LCL-based propery grid UI controller
|
|
cmdlinelclutils.pas - the function contains a number of utility functions
|
|
for allocating LCL controls based on the information about command-line option
|
|
|
|
=== Lazarus specific ===
|
|
|
|
cmdlinelazcompopt.pas - Lazarus IDE specific file, that converts a set of cmdlinecfg classes
|
|
to Lazarus project
|
|
=== Condition checks ===
|
|
|
|
cmdlinefpccond.pas - the utility function for verification of FPC specific conditions (cpu/os)
|
|
(doesn't depend on cmdlinecfg.pas)
|
|
see "FPC Condition" below
|
|
|
|
|
|
== JSON Storage ==
|
|
|
|
The configuration can be stored in JSON format.
|
|
Root values are
|
|
|
|
executable : string - the name of executable (don't have to match the actual binary name)
|
|
must be the same accross multiple versions
|
|
version : string - the executable version.
|
|
testkey : string - the test command-line key that needs to be passed to the executable
|
|
to retrieve the test value
|
|
testValue : string - the value that's unique to this version of executable
|
|
option : array - an array of options, where each option is described as json object
|
|
fromversion : string - the version of the same executable that configuration file can be used.
|
|
thus "incremental" configuration files are allowed.
|
|
however, previous version of the file must be available as well.
|
|
Any new values or options
|
|
|
|
Option values are:
|
|
|
|
key : string (required) - the command-line text that needs to be added to a parameter
|
|
if the option is selected or any value is assigned to this option
|
|
(in case any value is accepted, such as: int, size, filepath, dirpath, etc)
|
|
name : string (optional) - code name of the option (the same name should be shared accross multiple
|
|
versions of the executable - to store the value);
|
|
section : string (optional) - the section of command line option.
|
|
subsection : string (optional) - the sub section of the section ... todo: make a better description here
|
|
masterkey : string (optional) - the "key" prefix that should be used to combining multiple values into
|
|
a single key entry. Example:
|
|
two switches -Ct -Co will be combined into -Cto, if both have -C as master key.
|
|
display : string (optional) - the display name of the option. (if blank, name is used)
|
|
condition : string (optional) - free form condition string (see FPC Condition below)
|
|
type : string (default switch) - the type of an option. Available types are:
|
|
switch - simple enabled or disabled
|
|
select - multple options are available (expected "options" to be defined)
|
|
filename - name of a file
|
|
dirname - name of a directory
|
|
int - an integer value
|
|
string - a free form string
|
|
- - (dash) if type is a dash, the option is removed from this version
|
|
of the compiler. (used with "fromversion" configuration)
|
|
options : array (optional) - a list of available values.
|
|
mutiple : boolean (default false) - multiple entries of the same value is allowed. typically
|
|
is used for filename or dirnames. However, even for dirname of filename
|
|
it still defaults to false and must be reinitialized;
|
|
alias : string (optional) - the current key is considered to be deprecated is, the better
|
|
key to be used is specified by the "alias" field
|
|
|
|
|
|
Example of JSON Storage:
|
|
|
|
{
|
|
"executable":"fpc",
|
|
"version":"2.6.0",
|
|
"testkey":"-iV",
|
|
"testValue":"2.6.0",
|
|
options: [
|
|
{
|
|
section:"execopt",
|
|
key:"Xm",
|
|
name:"generatelinkmap",
|
|
display:"Generate Link Map"
|
|
},
|
|
{
|
|
section:"codegen",
|
|
key: "Cp%value%",
|
|
display: "Instruction set",
|
|
name: "instructionset",
|
|
options: [
|
|
{ value: "80386", condition:"i386,x86_64" }
|
|
,{ value: "PENTIUM", condition:"i386,x86_64" }
|
|
,{ value: "PENTIUM2", condition:"i386,x86_64" }
|
|
,{ value: "PENTIUM3", condition:"i386,x86_64" }
|
|
,{ value: "PENTIUM4", condition:"i386,x86_64" }
|
|
,{ value: "PENTIUMM", condition:"i386,x86_64" }
|
|
]
|
|
}
|
|
]
|
|
}
|
|
|
|
|
|
|
|
== FPC Condition ==
|
|
|
|
Free Pascal Compiler condition define for what target (CPU, CPU-OS) the option or value of an option
|
|
is available. The format follows the FPC convention of target platforms naming:
|
|
CPU-OS
|
|
or
|
|
CPU
|
|
|
|
Example, if an option is available for Intel 386 (32-bit machines), the condition should be set to
|
|
i386
|
|
If an option is specific to Windows on i386 machine, the condition would be
|
|
i386-win32
|
|
(No whitespaces are allowed between)
|
|
|
|
If an option is available for multple platforms, each condition has to be comma separated:
|
|
i386,x86_64,arm-linux
|
|
|
|
|
|
== UI controller ==
|
|
|
|
UI controller is an abstraction layer, that does the representation of the command-line utils to an user.
|
|
|
|
The core class is:
|
|
|
|
TCmdLineUIControl
|
|
method
|
|
procedure Init(cfg: TCmdLineCfg; layout: TCmdLineLayoutInfo; ASection: string);
|
|
- method accepts the description of the command-line options
|
|
and optional layout information;
|
|
method must initialize (create) all necessary UI controls;
|
|
the place to initialize controls must be defined in the method constructor
|
|
* if layout information is passed, the controller should use it to represent the user interface
|
|
* if Asection is not an empty string and layout is passed, controller should
|
|
initialize controls for this section only.
|
|
Futher operations for "SetValue" and "Serialize" should be limited
|
|
to the command-line options, contained in the layout of the passed section.
|
|
if layout information is not passed, section should be ignored
|
|
* Since it's possible that a new command-line option is introduced
|
|
prior to update of the user interface information,
|
|
a layout information can specify switch "%%other" (name is case-insesitive)
|
|
where all switches should go, that don't have a specific location within the layout information.
|
|
if "%%other" switch is not introduced by the layout, these command-line options that are not part of the layout
|
|
must not be shown.
|
|
if multiple "%%other" switches are declared, the first met should be used
|
|
|
|
procedure SetValues(list: TList);
|
|
- method should initialized UI controls to the values passed in the list
|
|
the list will contain objects TCmdLineOptionValue class.
|
|
the methods must not retain or free any of the objects
|
|
procedure Serialize(list: TList);
|
|
- method should gather the values from the user interface
|
|
method should not check the existense of TCmdLineOptionValue in the passed list
|
|
instead it must only ADD serialized TCmdLineOptionValue values
|
|
|
|
events
|
|
OnValueChanged: TNotifyEvent - the event should be triggered every time a value is changed by a user;
|
|
the even must not be triggered during handling of SetValues method
|
|
|
|
|
|
|
|
The supplemental classes:
|
|
|
|
TCmdLineLayoutInfo - the class contains a description of how to represent command-line utils.
|
|
any implementation of TCmdLineUIControl must be able to work without
|
|
any TCmdLineLayoutInfo provided.
|
|
TLayoutSection - the description of a certain section of "command-line configurations".
|
|
typically command-line options are grouped into sections
|
|
|
|
=== GUI Hints ===
|
|
|
|
hideempty - if the there're no command-line options to be displayed, the section should be hidden |