User Tools

Site Tools


project_system_lesson.htm
Navigation:  User's Guide and Tutorials > Project System >====== Project System ====== Previous pageReturn to chapter overviewNext page

All of the components that are used to create the final executable (target file) for your application is managed by a Clarion Solution file (*.SLN) . The project file (contained in every solution, and using a .CWPROJ extension) stores the compiler options ranging from whether to include debug code or not, to setting a preferred optimization method. The compiler and the linker depend on this project information to tell them how, and what, to compile and link. The project information is functionally equivalent to a MAKE file for other language compilers.

The Clarion Project System visually manages the project information. It maintains tree diagrams of the source files, external libraries, resources, and other project components.

ProjectPad.jpg

This chapter discusses the Project System and related topics. It shows you how to:

·Add source code files to the Project Tree.

·Add external libraries to the Project Tree, and how to access their functions and procedures in your source code.

·Specify the target file and set other compiler options. The target file is the ultimate executable created for your application or project

Hand Coded Projects

This section provides an overview of the steps necessary to create a solution file (*.SLN), and associated project file (*.CWPROJ). The project file tracks all the components that are used to create the executable file. It also sets the compiler options ranging from whether to include debug code or not, to defining switches.

If you use the Application Generator to create your source code, the project files are created automatically, and the only thing you will probably use the Project System for is to set debugging options. The Application Generator takes care of maintaining most everything else for you. Therefore, this chapter is primarily concerned with using the Project System for hand-coded programs.

The Project Tree dialog organizes all the project components and provides access to other dialogs that manage your project file.

To create a solution and project file

1.Choose File BLTTRIA.jpg New BLTTRIA.jpg Solution, Project, or Application. or press the New Project button NewSolution.jpg on the IDE toolbar

This opens the New Project dialog. The Categories list contains all available code platforms currently registered in the IDE. The Quick Starts list contains all available targets for the selected category.

In this topic we will focus on the Clarion for Windows category. For handcoded executables, the Win32 EXE Quick Start is selected, as shown below:

NewProject1.jpg

2.In the Name entry, enter a descriptive name for your project. By default, this will be the name of your project's target output, by this can be modified later in the Project Properties if needed.

3.In the Location entry, enter (or select with the Browse for Folder dialog after pressing the ellipsis button) the location where the project will be created.

4.Optionally check the Create directory for Sources and Auto create project subdir boxes to create additional project folders if needed

5.Press the Create button.

This opens the Solution Explorer dialog, and the Text Editor with your program's source file loaded.

Add Project Components

1.RIGHT-CLICK on any Project Tree component category (such as Database driver libraries), then choose the Add <;component> menu item.

This opens a dialog where you can select a component of the specified type. For Database driver libraries, the Add File Driver item calls the Select File Drivers' dialog so you can choose from a list of valid Clarion database drivers. In nearly all other instances, the Add <;component> item opens the Windows File dialog to help you locate the component file.

2.Select the component file to add it to your project.

3.Repeat the above steps for all component files.

Set Global Make Options

1.In the Solution Explorer, select (CLICK on) the Project (first) line then press the Properties button in the Solution Explorer toolbar.

ProjectProps.jpg

This opens the Project Properties dialog. This dialog sets various compile and link options for your entire project, including optimization method, type of executable created, whether to include debug code, etc.

Select the tabs in the Project Properties dialog to get an idea of the available options, or press the Help button to see a description of each option. See the core help Project Properties ' Clarion Win32 topic for more information on these compile and link options.

Set Local Make Options

Like the Add <;component> menu item, the Properties button behaves differently depending on which Project Tree folder is highlighted. When a source file is highlighted, the Properties button calls the Properties Pad dialog. This dialog sets compile options for the specific source file highlighted. Specific compile options take precedence over global compile options.

CompileOptions.jpg

For now, select the property entries in the Properties Pad dialog to get an idea of the available options.

Compile and Link Options

This section provides an overview of the steps necessary to maintain a project file. Maintaining the project file includes adding and removing source files, object files, libraries, etc. from the compile and link process. In addition, you may set both global and local compile and link options in the project file.

Here is a detailed look at the Project System's Compile and Link Options.

Configuration Specify which Project configuration options you wish to set. Select Build or Release from the drop list provided. To change the Build target, use the Build/Set Configuration menu option.
Platform Current default is AnyCPU.
Target Name The output filename of the project. The Project System will use the description next to the Project name in the Project View tree list. It will also be the default project target filename (<;output name.output.type>). Macros are allowed, but only %V%, %X% and %L%.
Output Path The default target is based on the Project folder name and Build Configuration (e.g., <;projectfolder>\debug or <;projectfolder>\release). Use this option to specify an alternative target path where the target EXE, LIB, or DLL will be copied to. The only time you might want to use this is if you want to temporarily output a program you are creating to a different directory to preserve an old executable.
Output Type Specify the type of executable file: choose .EXE, .LIB, or .DLL from the Target Type drop down list.
Link Mode Specifies how the runtime library is called by the target file: choose DLL LIB, or CustomDLL from the Link Mode drop down list.:
DLL Uses the Clarion runtime library DLL (and database driver(s) .DLLs). It is called ClaRUN.DLL.
LIB Links the runtime library and any database drivers into your executable using Smart Method Linking (only the necessary portions are linked in). This creates a “one-piece” executable.
CustomDLL Specifies that another External DLL contains the runtime libraries and database drivers. The calls to this DLL must be exported.
Application icon By inserting .ICO files after the Application icon item, you can link the icons into your executable so they do not have to be shipped separately.
Project Information Displays the Project folder, Project file and Output name. These items are read-only.

blk2blue.jpg

Component Files

This section explores the Project System's individual component files.

Projects to Include

The Project System can compile and link other projects referenced in the current project file. The other project can even specify yet another, in a cascading sequence of compile references.

Cascading projects lets you split the development process into separate projects, then link them all together when you're ready.

·To add a project to the Project Tree, RIGHT_CLICK on the Projects to include in the Project Tree list, and select the Add Project to Include menu item. Select the project file you wish to add with the standard Open File dialog.

Source Code Files

Source code files are those files that contain your Clarion Language statements (and other support statements). Adding a source code file to the Solution Explorer dialog is simply a matter of right-clicking on the project node and selecting one of the Add Item options..

External Source Files

To add “hand-coded” source code files, RIGHT-CLICK on the Project name then select Add Exixting Item from the popup menu and select the file you wish to add with the Windows file dialog.

Generated Source Files

For application (*.APP) files, Generated source files cannot be added or deleted with the Project System. They can only be added or deleted with the Application Generator. Any attempt to add these source modules will add them to the External source files.

Database Driver Libraries

Your application calls various database driver routines to access your database tables. These routines are in libraries supplied with Clarion and installed by default in the \LIB subdirectory by the Clarion setup program. During the link process, references to these external routines can only be resolved if the library containing the routines is added to your project file.

The Application Generator automatically adds the appropriate driver libraries based on the Data Dictionary table driver selections. For hand coded projects, you should manually add the appropriate driver libraries.

·To link a database driver library, RIGHT-CLICK on File Drivers in the Solution Explorer list and select the Add File Driver item and select the driver to add from the Select File Drivers to Include dialog.

Library, Object, and Resource Files

Libraries and Objects

An object (.OBJ) file contains objects'routines, functions, or procedures that can be linked into your program during the link process. A library (.LIB) file is simply a file that contains multiple objects. When properly linked, your program can call on these objects to perform certain tasks.

TipBox.jpg

You can create .LIB files for use with your Clarion applications. This topic is discussed in more detail in The Target File topic below.

Objects used in this manner need not be written with Clarion. Your Clarion programs can call objects compiled from C, C++, Pascal, etc.

To link a library, object or resource file, RIGHT-CLICK on the Solution Explorer's Library, object, and resource files folder, and then select the Add Library, Object or Resource File(s) menu item and select the file you wish to add with the Windows file dialog.

The .LIB, .OBJ, .RSC, etc. file appears in the Project Tree, and any objects from the file that are properly referenced in your source code are linked into your target (executable) file.

Resource Files

A resource file is any other file (.RSC, .ICO, .BMP) that should be linked into your program. One of the most likely things you'll do with the Project System is to specify resources to link into your executable. By linking them into the executable, you avoid having to ship them as separate, external files.

If you directly reference a graphic file within a data structure, the compiler automatically links the graphic, so there is no need to add the graphic file to your Project Tree. For example, if you place an IMAGE control in a window, and specify a file by name in the Image Properties Pad dialog, the linker automatically includes that file in your executable. But if you assign a different graphic to a control using a run-time property assignment statement, the linker will only include the new file in your executable if you add the file to your Project Tree.

TipBox.jpg

The Clarion runtime libraries assume the .EXE or .DLL where a window was most recently opened is where any referenced icons are located.

To add graphic files to the executable

1.RIGHT-CLICK on the Solution Explorer's Library, object, and resource files folder, and then select the Add Library, Object or Resource File(s) menu item

Select Image Files as the Files of Type filter, and then select the bitmap, icon, or metafile graphic from the standard Open File dialog.

2.Press the OK button to return to the Solution Explorer.

3.DOUBLE-CLICK on the source code file that references the graphic. The Text Editor opens the source code file.

4.Place a tilde (~) in front of the graphic file name in the source code assignment statement (not in the data section).

For example: change

?Image{PROP:Text} = 'I.ICO'

to

?Image{PROP:Text} = '~I.ICO'

The tilde indicates the program should find the item as a linked in resource, not as an external file.

Optionally, choose Search BLTTRIA.jpg Find to locate the file name.

5.Choose File BLTTRIA.jpg Close BLTTRIA.jpg File, then click on Yes when asked if you want to save.

Now, when you recompile and link, the executable will no longer require the external graphic file.

More Project Options

Nestled in the Project Properties dialog are many other powerful options to your project. Here are some highlights.

Build Events

Build Events lets you customize the compile and link process by executing the program(s) of your choice at the beginning or the end of the build process. These can be .BAT files or more sophisticated .EXE files that perform any additional tasks you specify as part of the compile and link process.

·To add a build event to the project, select the Build Events tab in the in the Project Properties dialog. Then select the pre or post event and enter the program file(s) you wish to add. Use the ellipsis to select an item from the Windows file dialog.

blk2blue.jpg

The Target File

Using the Project System, you can create .EXE, .LIB, and .DLL files. This section describes these three target file types and how to create them. More information can be found in the Distributing Files section below, and see also Development and Deployment Strategies.

·By default, the project system creates a standard executable (.EXE) file, which you distribute with ClaRUN.DLL. When you name the project file in the New Project File dialog, it automatically sets the Output Type extension to EXE and the Link Mode to Standalone in the Application Project Properties.

·To create a library (.LIB file), simply change the Output Type extension located on the Project Properties Application tab.

·To create a dynamic link library (.DLL), simply change the Output Type extension located on the Project Properties Application tab.

TipBox.jpg

Setting the Project's Output Type is equivalent to setting the Application's Destination Type and vice versa. See the Application Properties dialog.

.LIB Files

Library files (.LIB) contain procedures and functions that are linked into your executable at compile time. To create library files that may be accessed by Clarion, or by any of the other TopSpeed compilers, just set a .LIB file as the target file.

To use procedures and functions from a precompiled .LIB file, you must prototype the procedures and functions called by your program. Prototyping is accomplished by adding a MODULE structure to your application's MAP. To call an external .LIB procedure from “hand coded” source:

1.Add a MODULE structure to your application's MAP.

The MODULE should reference the external library file. In the Application Generator, you can place this in the Inside the Global Map embed point.

2.Add the procedure prototypes:

Example:

 MAP

  MODULE('EXTERNAL.LIB')

   ExtProc(*CSTRING),RAW

   ExtFunc(USHORT, *BYTE[]),USHORT

  END

 END

Each prototype specifies the name of the procedure, the data types of any parameters (in parentheses), and the return data type (if any).

In the example above, the ExtProc procedure expects the address (without the length, hence the RAW attribute) of a CSTRING to be passed to it as a parameter.

The ExtFunc procedure expects the value of a USHORT variable, the address of an array of BYTEs, and will return a USHORT.

3.To specify a different calling convention, add it to the prototype.

You may use .LIB or .OBJ files created by other compilers.

Modifying the above examples, the first line below identifies a procedure expecting the C calling convention. The second line identifies a procedure expecting the PASCAL calling convention, which is the Windows standard calling convention:

ExtProc(*CSTRING),C,RAW

ExtFunc(USHORT, *BYTE[]),USHORT,PASCAL

4.To optionally specify a third party linker's identifier, add it to the prototype.

Some compilers, most notably 'C' language compilers, add a leading underscore to the name of procedures and functions at compile time. The examples below add the NAME attribute:

ExtProc(*CSTRING),C,RAW, NAME('_ExtProc')

ExtFunc(USHORT, *BYTE[]),USHORT,PASCAL,NAME('_ExtFunc')

For more information refer to the Language Reference Help regarding the following topics: MODULE, MAP, PROCEDURE, and prototypes for more information.

.DLL Files

Dynamic Link Libraries (.DLL) contain procedures that are linked to your application at run-time. To create dynamic link libraries, just specify .DLL as the target file extension.

To call a .DLL procedure, follow the steps outlined for calling a .LIB procedure, above.

TipBox.jpg

Setting the Project Properties's Output Type is equivalent to setting the Application's Destination Type and vice versa.

blk2blue.jpg

Distributing Files

This topic describes the different program distribution options available to you.

Choosing a Configuration

This section is included to help you decide what kind of target file to specify for your project. Also see Development and Deployment Strategies.

Clarion produces executable files which you may distribute on a royalty-free basis. The applications you distribute require Windows 2000, NT, XP or Vista versions.

Clarion executables come in two flavors: .EXE files, and .DLL files. An .EXE file is simply an executable program. A .DLL (Dynamic Link Library) file is executable code that is linked into an .EXE file at run-time. This is in contrast to .OBJ and .LIB files which are linked into an .EXE at compile time. The most obvious benefit of the .DLL is that it provides a method of modifying .EXE operation without remaking (compiling and linking) the .EXE.

Clarion executables may be distributed in three configurations:

1.*.EXE ( A one-piece .EXE)

A one-piece .EXE will usually be larger than an .EXE distributed with .DLLs. However, the one-piece .EXE will probably be smaller than the combined sizes of an .EXE and its associated .DLLs.

The one-piece .EXE is made as small as possible by Clarion's smart linking process that only links in procedures actually called by the application program (whereas the .DLL contains a fixed set of procedures, whether or not they are actually called by your program).

A one-piece .EXE cannot have conflicts or problems that arise from linking with the wrong .DLLs at run time.

Make (compile and link) time for a one-piece .EXE is greater than for an .EXE combined with .DLLs.

TipBox.jpg

To make a one-piece .EXE follow the steps described in Development and Deployment Strategies.

2.*.EXE + Runtime library (ClaRUN.DLL)

Splitting the executables between .EXEs and .DLLs allows for more efficient use of disk space. Many Clarion applications (.EXEs) can share a single ClaRUN.DLL. Or, a single application suite with several .EXEs can share a single ClaRUN.DLL. However, as a developer, you must ensure that your application accesses the correct version of the runtime library.

An example of .DLL usage is the typical accounting system where the .EXE controls the system main menu, and calls system subparts such as Accounts Receivable and Accounts Payable from separate .DLLs. This method of distribution allows for program parts to be sold and maintained separately.

NoteBox.jpg

Splitting executables between .EXEs and .DLLs allows for more efficient use of disk space, but less efficient use of RAM. This is because the Windows operating system loads an additional ClaRUN.DLL into memory for each active Clarion executable, and because the ClaRUN.DLL contains some procedures your .EXE never calls.

To make an .EXE + ClaRUN.DLL: in the Project Properties dialog within the Project System, set Output Type to .EXE and set Link Mode to Standalone.

3.*.EXE + ClaRUN.DLL + *.DLL1 + … + *.DLLn

This configuration offers the same advantages and disadvantages as the .EXE + ClaRUN.DLL configuration. It is listed here to illustrate that you are not limited to a single .DLL, nor are you limited to Clarion .DLLs. Your Clarion applications may make use of .DLLs compiled from other languages as well as the ClaRUN.DLL and the SoftVelocity database driver .DLLs.

4.*.EXE + *.DLL1 + … + *.DLLn

This configuration offers most of the same advantages and disadvantages as the .EXE + ClaRUN.DLL configuration. It is listed here to illustrate that the ClaRUN.DLL may be linked into another .DLL. This technique “hides” the ClaRUN.DLL and ensures that your application will never get the wrong version of ClaRUN.DLL, because, technically, it isn't looking for ClaRUN.DLL.

TipBox.jpg

To “hide” ClaRUN.DLL in another DLL, follow the steps described in the Development and Deployment Strategies topic.

Installing and Accessing Your Application's DLLs

If you distribute ClaRUN.DLL, it must reside in the same directory as the application program, in the Windows\System subdirectory, or in a directory referenced in the system PATH. We recommend that you install ClaRUN.DLL to the application directory.

Remember, multiple Clarion applications may use the same ClaRUN.DLL file, thus saving space on the users' hard drive. On the other hand, sharing a single ClaRUN.DLL raises the possibility of conflicts among applications developed under different versions of Clarion. To avoid possible conflicts, install a separate ClaRUN.DLL to each application directory, or distribute the application as a single .EXE file, or link the ClaRUN.DLL into another .DLL that is unique to your application.

The Ship List

For generated applications, Clarion templates automatically create a ship file (.SHP) that contains the names of the files that are needed to run your application. The file is called application.SHP and is in the same subdirectory as your .APP file.

This ship file only includes those files that are visible to the templates. Any DLLs loaded in EMBEDs or INCLUDE files may not be visible to the templates, and may not be in the list.

In the case of external library modules, the .LIB file is also included in the list. Some of the .LIBs (WINDOWS.LIB for example) do not have associated DLLs; however, most do have associated .DLLs that you will need to distribute with your application.

In the case of an external library module generated by Clarion, you must ensure that all files on the shipping list for that LIB/DLL are also included.

TipBox.jpg

You can modify your application's ship list by embedding text at the Inside the Shipping List Global Embed point.

project_system_lesson.htm.txt · Last modified: 2021/04/15 15:57 by 127.0.0.1