_USES Uses Report

Top  Previous  Next

 

Targets: All

 

For a normal PAL project, this report consists of eight sections:

 

Unit usage (USES1)

Modules not needed in the Delphi project file (USES2)

Modules not added to the Delphi project file (USES3)

Unit references (USES4)

Optimal uses list (USES5)

Runtime initialization order (USES6)

Mutual unit references (USES7)

All modules (USES8)

 

For multi-projects there are two sections:

 

Units used by the projects (MUSE1)

Units used by all projects (MUSE2)

 

Please note that the Uses Report reports units from all folders, even from those that are set as excluded in the project options.

 

An additional file Lattix.xml is always created in the report directory. It is a file that you can use to integrate with Lattix products, if you use them.

 

 

 

Unit usage

 

This report section lists all units that PAL is able to find. For each unit, the uses statements are analyzed. The units specified in these clauses are listed, indicating if they are actually used. Units that have initialization sections are specially marked. It is often desirable to keep those units in the uses lists, even if they are not formally needed, in order to execute the initialization code.

 

Removing unused uses references has multiple benefits:

 

- cleaner code to maintain, no need to bother about code that is not used

- code from initialization and finalization sections in unused units is not linked in and run, reducing the size of the EXE

- resources (icons, bitmaps etc) used by referenced units are not linked in

- compilation runs smoother and quicker

 

Units specified in the interface uses list are categorized as:

 

Unnecessary

Used in unknown way

Used in interface

Used in implementation

Used by inherited form

 

You can probably remove units categorized as “unnecessary from the uses list. If they are categorized as “used in implementation, move them to the uses list in the implementation section.

 

Units used by base forms (in form inheritance), are also listed by the Delphi IDE for child forms even if they are not needed for the compilation.  Trying to remove such a reference will only result in the IDE reinserting the declaration when the unit is saved. These situations are detected and the unit is listed as "used by inherited form" instead of "unnecessary".

 

Units specified in the implementation uses list are categorized as:

 

Unnecessary

Used in unknown way

Used in implementation

 

You can probably remove units categorized as “unnecessary from the uses list.

 

A special case is Delphi project files (DPR-files). The units listed in the uses list in the DPR-file are often not referenced in that file, and PAL consequently categorizes them as unnecessary. Nevertheless, you probably want to keep them in that uses list, so they are available to Delphi’s Project Manager.

 

When you drop a VCL component on a Delphi form the Delphi IDE automatically adds the unit or units required by the component to the interface section uses statement. This is done to ensure that the form file (DFM/XFM) can locate the code needed to stream the form and components. Even if you later remove the component, the units are not deleted from the uses statement. This causes the need to sometimes clean the uses statement of unused units. In addition, units that you add manually may be left behind in the uses statements if you later delete the code sections that need these units.

 

Even if the compiler does not include code from units that are never used, the initialization section (or finalization section) is included in the EXE file regardless of whether any methods from the unit are used or not. Also resources may be linked into the final EXE. One tip here is to generate and examine the MAP-file. The initialization section is also always executed when the application starts. This is a good reason why you should remove superfluous units from the uses lists. It will also make compilations more efficient. The fewer units in the uses clause, the quicker the compiler can do its job.

 

Sometimes, PAL determines that a unit is not needed, but Delphi reinserts it anyway into the uses-list when the unit is saved. This happens when working in the Delphi IDE.

 

If a project uses conditional compilation, maybe a unit is sometimes needed and sometimes not; such a unit must remain within a project. You could wrap conditional defines around such a unit declaration in the uses clause, like:

 

clip0129

 

There is an option “Only warnings” for the Uses Report in the Properties dialog. Select this checkbox to only report those units that can be removed from the uses list or moved from the interface to implementation uses list. The default value is FALSE.

 

 

Modules that are referenced in the Delphi project file, but not used

 

This section lists all units that are included in the Delphi project file, but are not used. These references can probably be removed from the project file. One reason to include them in the project is to make them accessible from the Project Manager in the Delphi IDE.

 

 

Modules that are used but not added to the Delphi project file

 

This is a list of units that are used, but not added to the Delphi project file. One reason to include them in the project is to make them accessible from the Project Manager in the Delphi IDE.

 

 

References

 

This section lists for every unit, which other units that are referenced. It also lists all units that reference this unit.

 

 

Optimal uses list

 

This is a list of the units, in the order that they are parsed by PAL.

 

It is a good idea to keep general units placed before less general units in the uses lists, for the compiler to run as smoothly and quickly as possible. You can use the Optimal Uses list to achieve this aim.

 

 

Runtime initialization order

 

This section lists the order in which the initialization sections are executed at runtime.

 

 

Units used by the projects

 

This section, which is available only for multi-projects, lists all units used by the projects.

 

 

Units used by all projects

 

This section, which is available only for multi-projects, lists all common units used by all analyzed projects.

 

 

Mutual unit references

 

This section lists units that reference each other. This leads to a strong coupling between the units, which is usually to be avoided.

 

 

All modules

 

This section lists all referenced units in the project, regardless if the source is found or not. Use the section to get an overview of the used units.

 

 

 

See also:

 

R_REF Reference Reports