How To Use HNDCLEAN.EXE

This version of HNDCLEAN.EXE (Version 21.17.02.004 or later) lets you configure it in such a way, that it KNOWS about redirection locations (alternate gen-file output directories) that you may have configured in our Clarion .RED file.

When you configure HNDCLEAN.EXE for your normal RELEASE operations, it's necessary to tell it where your template-generated output is going. Even with a default .RED, HNDCLEAN.EXE will not assume anything about how you're configured unless you tell it explicitly.

Sample Setup With Co-Relative Subdirectories

HNDCLEAN.EXE takes up to four input parameters. These are as follows:

PARAMETER 1 -- REQUIRED ---  [P2 OPT]   [P3 OPT]     [P4 OPT]
${TargetDir}\${ItemFileName} subdir1 supdir1\subdir2 subdir1\subdir2\subdir3


All parameters require at least a single space between them. All directories provided are rooted in ${TargetDir}. Hence, they are relative directories -- relative to the value in ${TargetDir}. When directories in P3 and P4 are chained as shown, these become co-relative sub-directories meaning that each of the "subdir" parameters places itself below the prior one.

Given an input for ${TargetDir} of "c:\test" the full set of clean directories as configured above resolves as follow:

c:\test\  (This is ${TargetDir} which comes up from the IDE)
c:\test\subdir1  (Passed in, optional Parameter 2)
c:\test\subdir1\subdir2  (Passed in, optional Parameter 3)
c:\test\subdir1\subdir2\subdir3  (Passed in, optional Parameter 4)


Sample Setup With Simple-Relative Subdirectories

HNDCLEAN.EXE takes up to four input parameters. These are as follows:

PARAMETER 1 -- REQUIRED ---  [P2 OPT] [P3 OPT] [P4 OPT]
${TargetDir}\${ItemFileName} subdir1 subdir2 subdir3


All parameters require at least a single space between them. All directories provided are rooted in the ${TargetDir}. In this case, because P3 and P4 make no reference to P2 or P3, respectively, these paths are "simple" subdirectories, all rooted in ${TargetDir}.

Given an input for ${TargetDir} of "c:\test" the full set of clean directories as configured above resolves as follows:

c:\test\  (This is ${TargetDir} and comes up from the IDE)
c:\test\subdir1  (Passed in, optional Parameter 2)
c:\test\subdir2  (Passed in, optional Parameter 3)
c:\test\subdir3  (Passed in, optional Parameter 4)


 

 

 

 

 

CHT HNDCLEAN.EXE Setup With Co-Relative Paths

 

CHT Test "CLARION100.RED" File Setup To Match Above Image

 

 

How The IDE Determines The Value of ${TargetDir}

The secret to successful CLARION100.RED configuration is knowing how the default output directory is determined. This is the value that's inserted into the IDE MACRO ${TARGETDIR}.

In fact TARGETDIR is the directory in which the .APP file being worked on is located. If you wish to refer to this HOME or TARGETDIR in the .RED configuration, you do so with a DOT. Our sample .RED configuration set up for [Release], allows six file extensions to be generated into the ${TargetDir} location, indicated simply by a DOT.

That's why we use an IDE MACRO ${TargetDir} as the first half of our first (P1) HNDCLEAN.EXE input parameter. The second half of our first parameter is ${ItemFileName}. This is the name of the application currently loaded for Generate-Compile activity. Note that in Image 1 above, we've separated ${TargetDir}\${ItemFileName} with a backslash to provide a full legal path to the application.

Where your app is located, then, comes up from the IDE and the value provided to ${TargetDir} depends on where the application that you're working on is located. The remaining output sub-directories are RELATIVE to that one ${TargetDir} location.

Locating Test Application HNDVIDEOPLAYER.APP
Into C:\TEST

To test the viability of our setup we placed three files into a directory called "c:\test". Since this application requires no dictionary, the files used are:

C:\TEST\HNDVIDEOPLAYER.APP
C:\TEST\HNDVIDEOPLAYER.CWPROJ
C:\TEST\HNDVIDEOPLAYER.SLN


We loaded the application into the Clarion 10 IDE and forced a full Regenerate/Compile on the freshly loaded application as using the Generate and Make Current Application menu as in the next image.

Generating HNDVIDEOPLAYER.APP
Into C:\TEST

The next image provides the files created by the execution of the "Generate and Make Current Application" menu against our test application HNDVIDEOPLAYER.APP.

Remember we're starting with only 3 files, enumerated above. Some of these files (eg: .CLW, .INC, .VERSION etc.) are the result of the action of code-generation. Some of these files (eg: .OBJ. .MAP, .RSC etc.) are the result of the action of code-compilation.

"Generate" and "Make" (i.e. Compile) are two entirely separate IDE actions invoked when the "Generate and Make Current Application" menu is used.

After "Generate" and "Make" the resulting file count jumps to thirty-five (35), located in the four directories configured ealier in our CLARION100.RED.

• C:\TEST -- 10 Files created. (i.e. ${TargetDir} Parameter 1)
• C:\TEST\CLEAN -- 7 Files created. (i.e. Parameter 2)
• C:\TEST\CLEAN\CLW -- 9 Files created. (i.e. Parameter 3)
• C:\TEST\CLEAN\OBJ\RELEASE -- 10 Files created. (i.e. Parameter 4)

A quick review of our CLARION100.RED setup -- see Image 2, above -- will confirm that these file extensions are located where they were configured to be located.

 

 

 

 

 

 

 

 

 

 

 

Testing The IDE "Clean Solution" Menu

The major reason we're spending so much time testing and perfecting HNDCLEAN.EXE is because we've found that Clarion 10 does not provide a full enough cleaning service that will trigger both a full Re-Generate and a Full-Recompile.

The Clarion 10 "Clean Solution" or "Clean hndvideoplayer" menu do trigger removal of the .OBJ files resulting from the compilation of HNDVIDEOPLAYER.APP generated source files.

Unfortunately, neither of these menus, as our test image below proves, triggers removal of any generated code files. Consequently applications requiring a full-regenerate in order to trigger code from newly added templates or from changed template settings requires sometimes a maneuver as drastic as exiting and re-loading the application before full code regeneration is achieved.

Before discussing that further, take a look at the files-count resulting from a the IDE's "Clean Solution" menu. [Image 6 Below]

Of a total of 35 original files, only 10 files were deleted. Leaving 25 files as can be seen in Image 6.

All directories save the C:\TEST\CLEAN\OBJ\RELEASE still contain the same file count as before the "Clean" operation was performed.

As explained above, this is fine for triggering a "re-compile" of the application source code but it does not trigger the IDE to "re-generate" the application.

The "Clean" operation derives from functionality built into MSBUILD, an environment that does not incorporate the concept of code-generation, at least not to the extent that Clarion generates code.

MSBUILD considers code files to be static unless touched and edited by human hands or at least, modified by some action on the VS (Visual Studio) interface.

That may explain why Clarion "Clean Solution" or "Clean myapp" do not also erase generated-code files.

Unfortunately, again, it's less than satisfying to understand this when a developer knows they've made changes to their application template settings in various places and they want to trigger a full-regenerate to ensure that all template setting changes are being generated into the code files.

 

CHT HNDCLEAN.EXE To The Rescue!

Image 1 above, explains how we set up HNDCLEAN.EXE on the Clarion Tools menu with input parameters that match the co-relative subdirectories configured in our CLARION100.RED file. If you need to recheck that before reading on, please do so now.

To execute an item on the Clarion IDE's "Tools" menu, where HNDCLEAN.EXE has been added, pull down "Tools" and click the "CHT Clarion Gen-Code Cleaner" menu item now located there. That's all there's to it.
[See Image 7]

 

Examining The Result Of Clicking The
CHT Clarion Gen-Code Cleaner Menu

Back in the "c:\test" directory, we show you now the remaining files list resulting from executing the CHT Clarion Gen-Code Cleaner menu.

Only 7 files remain from the original 35 files. HNDCLEAN.EXE removed the rest. Let's examine which files are left and why they are being left untouched.

The following files names remain in the C:\TEST directory. Note that there are no files remaining in any of the configured co-relative sub-directories. This may not always be the case depending on whether your application is pure-CHT or whether it contains other 3rd party templates, some of which, we know, also generate file extensions unique to them. Even CHT template settings can affect the total number of files generated, obviously.

The important point here is that HNDCLEAN.EXE is deleting the bulk of our application's generated files, ensuring that the code-content of these files is refreshed completely from the application templates.

C:\TEST\HNDVIDEOPLAYER.APP  (The original application)
C:\TEST\HNDVIDEOPLAYER.AP~  (The original application's temp file created when app is open)
C:\TEST\HNDVIDEOPLAYER.BPP  (The original application's backup file created by the IDE)
C:\TEST\HNDVIDEOPLAYER.CWPROJ  (The original application's project file)
C:\TEST\HNDVIDEOPLAYER.SLN  (The original application's solution file)
C:\TEST\HNDVIDEOPLAYER.CWPROJ.FILELIST.XML  (Required by the IDE "Clean myapp" menu)
C:\TEST\HNDVIDEOPLAYER.VER  (CHT-Genearated App version file used by other CHT templates)

While an extensive set of 35 generated or compile-created files emanated from only three original files, you can see that HNDCLEAN.EXE performed a far more extensive "Clean" operation than the IDE's native "Clean Solution" or "Clean myapp" menus.

The operation of HNDCLEAN.EXE WILL RESULT in the IDE's "Generate and Make" menu causing a full regenerate and a full recompile of your application.

This is going to be a real time-saver for us. We hope the same for you dedicated Clarion users.