Clarion Community Help

Compile and link options are specified in a project file by means of the #system, #model and #pragma commands.

#system

#system operating_system [ target_type ]

The #system command is used to specify the target operating system and file type. The macros %system and %filetype are set to the first and second arguments. See Special Project System Macros below.

The first argument specifies the target operating system, and may be win or win32.

The second argument indicates the target file type, and may be exe, lib, or dll. If omitted, exe is assumed.

The #system command affects the behavior of subsequent #model and #link commands. Therefore a #system command must be specified before either of these. If more than one #system command occurs in a project, each must be followed by a #model command in order to take effect.

#model

#model memory_model [ linking_convention ]

The #model command is used to specify the memory model to be used for subsequent compiles and links. This memory model will continue to be used until modified by explicit #pragmas, or by another #model command.

The #model command sets the macros %model and %jpicall to its first and second parameters respectively. For example,

#model clarion dll

is equivalent to

#set %model = 'clarion'

#set %jpicall = 'dll'

The first argument specifies the memory model, which is always 'clarion' for Clarion projects. The second indicates the linking convention, which may be dll, lib, or customdll. If omitted, dll is assumed.

Setting the second argument to dll indicates that you will be creating an exe or dll that calls the standard Clarion dlls. Setting the second parameter to lib indicates that you will be creating an exe, lib or dll that includes all the components of the Standard Clarion libraries (and file drivers) in the exe, lib or dll. Using customdll indicates that you are linking to a dll that was previously created with the lib link convention, so the standard Clarion dlls are not linked.

The #system command must be specified before the first #model command.

#pragma

#pragma <;#pragma> { , <;#pragma> }

The #pragma command modifies the state of the #pragma options which affect the behavior of the SoftVelocity compilers or linker. The syntax and meaning of all #pragmas are discussed under the SoftVelocity #pragmas section below.

The special macro %pragmastring expands to the current state of all #pragma options which are not in their default state - this can be useful for determining exactly which options are being used for a given compile. For example:

#message '%pragmastring'

Compile and Link Commands

Whenever a file is compiled or linked, the current settings of the compiler or linker options (#pragma settings) are compared to those used when the file was last compiled or linked, to determine whether the file is up to date. If a compile or link is necessary, the current settings are passed on to the compiler or linker.

#compile

#compile<;source> [ #to <;object> ] [ / <;#pragma> { , <;#pragma> } ]

{ , <;source> [ #to <;object> ] [ / <;#pragma> { , <;#pragma> } ] }

The #compile command causes each nominated source file to be compiled (if necessary). The name of the object file may be specified using #to. If this is omitted, the name is derived from the source filename, with the extension .obj.

Any #pragmas specified in a #compile command apply only to the single source filename that precedes the / character.

The macro %make is set to on if a compile is necessary, off otherwise. The macros %src and %obj are set to the names of the source and object filenames.

Each object file is added to the link list, i.e. there is an implicit:

#pragma link( %obj )

For example:

#compile fred.c #to fred.obj

#compile george.cpp /debug(vid⇒full)

It is possible to reconfigure the behavior of the Project System when compiling source files of a given extension using the #declare_compiler command. This may also be used to declare actions to perform for different file extensions - for example, to support third-party compilers or preprocessors. See Other Commands below.

#link

#link <;target_filename>

The #link command links together (if necessary) all the files in the link list to the nominated executable or library file. The file type is determined by the extension of the nominated target file, or, if there is no extension, by the file type specified in the most recent #system command. If neither are specified, the default is to produce an executable file. The effect of #link is to set the macro %link_arg to the specified filename.

The Project System maintains a list of those files that are to be used as input to the linker the next time an executable or library file is created. This list is known as the link list. A filename may be added to the link list using the #pragma link command.

For example:

#pragma link (mylib.lib)

However, it is seldom necessary to use #pragma link explicitly, as all the SoftVelocity compilers add the resulting object file to the link list whenever a source file is compiled using #compile. In addition, when the #link command is encountered, all required standard library files, and other object files which are imported by those already on the link list are also added to the list. The link list is cleared after each link.

The #link command differs from the similar #dolink command in that (so far as the Project System can determine), any additional object files required are automatically added to the link list before linking. This includes any SoftVelocity library files, and also (with an implicit #autocompile command) all modules imported with IMPORT clauses in SoftVelocity Modula-2 or with #pragma link statements in SoftVelocity C or SoftVelocity C++ source files. In addition, #link will determine from the target file type any additional processing that needs to be applied to the output file.

For certain specialized requirements, the use of #link may be inappropriate'for example, if a specialized startup file is required, or when building library files, where explicit control of exactly which files are included may be preferred. In such cases, the #dolink command should be used.

#dolink <;target_filename>

The #dolink command takes the object files which have previously been added to the link list, and combines them into an executable or library file (depending on the extension of the nominated target file), if required to keep the target file up to date. No additional files are added to the link list, so all required files must have been specified previously, by means of #pragma link, #pragma linkfirst, #compile, and #autocompile. For simple projects, the use of #link is preferable because the link list is dynamically maintained by the project system, freeing the developer from this responsibility.

When finished, the #dolink command clears the link list.

See Also:

#pragma link_options (link)

#autocompile

The #autocompile command examines the object files which are currently in the link list, to see which objects they need to be linked with. This would include objects specified using a #pragma link in a SoftVelocity C or C++ source file, or in the case of module based languages such as SoftVelocity Modula-2 imported modules.

Each resulting object file, which is not already in the link list, is then compiled (if necessary) and added to the link list. If there is more than one possible source for a given object file, an error is reported. This process is repeated until the link list stops changing.

It is not necessary to use #autocompile for simple projects where #link is used rather than #dolink, as #link performs an implicit #autocompile.

#ignore

#ignore <;filename>

#ignore #pragmastring

There are two forms of the #ignore command. The first, where a filename is specified, tells the Project System to ignore the date of the nominated file when deciding whether or not to compile. This is useful when a 'safe' change is made to a widely used header file, to prevent mass recompile.

The special form #ignore #pragmastring directs the Project System to ignore the #pragma settings when deciding whether or not to compile a file. This may be useful, for example, when a new compile-time macro has been defined, but there is no need to recompile everything.

#implib

#implib <;libfilename>

The #implib command is used to create (if necessary) a dynamic link library file. There are two forms of this command, which operate in slightly different ways. If a single filename is specified, this names an import library file, which is created (if not up-to-date) from the object files in the link list. The object files are scanned and each public procedure or variable is exported. For example:

#pragma link( fred.obj, joe.obj )

#implib mylib.lib

In the second form of the #implib command, an import library filename and a module definition file (.exp'see Module Definition File below) are both specified, and the library file is created (if not up-to-date) from the symbols named in the definition file. This form of the command is equivalent to using the tsimplib utility that comes with SoftVelocity C, C++, and Modula-2.

#implib <;expfilename> <;libfilename>

Using #implib in the second form requires you to create and maintain the list of exports 'by hand', whereas the first form exports all public names automatically. The use of a module definition file is an advantage if you need to maintain compatibility with previous versions of an interface, and it also allows you to export only the procedures which need to be exported.

When #implib is used with a module definition file, the link list is cleared.