trick/doxygen/users_guide/misc_utils.dox_in

/**
@page LEVEL1 Other Trick Tools

@section LEVEL3 Interface Code Generator - ICG

ICG is the processor that %Trick uses to parse header files.  It is normally called
internally from the main %Trick processor, CP.  However, it may be used manually by
developers.

@par
The ICG parses developer created data structure definition files and generates
runtime executive input/output source code.  The source code generated is compiled
into a simulation which uses the types parsed.

@par
The command syntax for the ICG is as follows (with restrictions outlined afterward):

@par
<tt><b>UNIX Prompt></b> ICG [-d] [-D <define>] [-U <undefine>] <filename>.h</tt><br>
<tt><b>UNIX Prompt></b> ICG -u</tt>

@par
The ICG can process multiple files at a
time and does accept UNIX wild card character designations (*.h) in the filename. The
optional ‘-d’ (for debug) argument tells the ICG to echo every character successfully
parsed from the file; if a syntax error occurs in the file, the user will know the exact
character which caused the problem.  The optional ‘-D’ and ‘-U’ arguments are compiler
directives, used in concert with #defines, #undefs etc. and work like their CFLAGS
counterparts.  The optional ‘-u’ argument tells ICG to display the current measurement
units primitives allowed in the parameter comment fields of the data structure definition
files.

@par
The ICG generates one source code file for each data structure definition file it
processes, with a file name in the form of io_src/io_<file_name>.c; where “io_” is a
standard prefix for all ICG generated files, and <file_name> is the original data
structure definition file name.

@par
Any characters or statements the ICG recognizes as valid syntax, but does not process,
will be echoed to the screen with an informative message on why it did not process the
parameter.

@par
In general, the following items are not processed by the ICG:
-# global parameters decalred outside of a struct, union, or enum typedef,
-# all parameter declarations of a type other than the basic C types listed in the
   Parameter Data Types section or the types contained within the data structure and
   enumerated type databases (structure and enumerated types previously processed by the ICG),
-# all parameters that have a ‘**’ in the measurement units field of the parameter comment, and
-# all function declarations.

@par
The ICG will always give the “ICG complete.” message upon successful completion of processing.

@section LEVEL3 Building Model Source

%Trick’s main processor, CP handles building models from a high level.  However,
developers may desire to build a local cache of source and include files in a model
directory.  Or the developer may want to build a library from a model directory of
source and include files.  %Trick’s make_build and UNIX’s make may be used for these
purposes.

@section LEVEL4 Makefile Generator - make_build
The make_build processor takes the src and include files in a model directory and
autogenerates a Makefile. Note that make_build will work for mixed *.c and *.h files
in the same directory or for src and include subdirectories. make_build generates a
complete dependency list for the source and header files processed. make_build should
only be run after the ICG processor has been run on all appropriate data structure
definition files. This ensures the io_*.c files created by ICG are processed by
make_build. The command syntax for make_build is as follows:

<tt><b>UNIX Prompt></b> make_build [lib <lib_name>]</tt>

The lib argument causes make_build to generate Makefile syntax for building an
archived (UNIX ar) library for the object files and give the library the name <lib_name>.

The make_build command is rarely used.

@section LEVEL4 Make Processor - make
Developers will be running GNU make on Makefiles in the SIM directory or model
directories.  Running make in a SIM_ directory with a Makefile generated by CP will
result, hopefully, in a simulation.  Running make in a model directory with a
Makefile generated by make_build will result in either object code for the model
source local to that directory or a library.

Makefile options may be found by typing in:

<tt><b>UNIX Prompt></b> make help</tt>

Additional documentation for make can be found in UNIX manuals for your workstation.

@section LEVEL2 Pickling And Unpickling A Simulation

Ever wanted to go to a sim directory and type in a command to get a tar-zipped file
of all simulation source necessary to run/build a simulation?

Welcome to pickle.

“pickle” is a script that does just that.

Here is an example of how to pickle a previously built simulation:

-# Build your simulation
-# cd ${HOME}/trick_sims
-# pickle SIM_ball_L2

This will create a file called SIM_ball_L2.tgz.

To “unpickle” your SIM_ball_L2.tgz and build it somewhere else, you take the following steps.

-# Untar and decompress the *.tgz file
-# source SIM_ball_L2_includes.csh (to get your TRICK_CFLAGS set)
-# cd SIM_ball_L2
-# CP

Caveat: Pickle will not search your input file for #includes on the system.
As long as you have all dependent input parameters in the SIM directory, it will
grab that.

@section LEVEL2 Viewing Parameters In SIE Database

Sometimes you are trying to remember the name of a parameter.... “Ummm. Let’s see.
It’s errr.  Uhhh.  clock something...”  Try running this in your built simulation
directory where the S_sie.resource file is located.

<tt><b>UNIX Prompt></b> sie [-nocase] <search string></tt>

As an example, if you know the parameter name contains clock but don’t know
anything else, try:

<tt><b>UNIX Prompt></b> sie clock</tt>

The search returns each %Trick processed variable (including %Trick’s “sys” variables)
from your simulation that contains the search string. Beneath each variable returned
is information from its header file definition: user supplied description, type,
input/output spec, and units spec.

For a case-insensitive search (e.g., to find occurrences of “clock” and “Clock”),
simply specify the -nocase option.

@section LEVEL2 kill_sim

The following command will kill all simulations and their children that you own.

<tt><b>UNIX Prompt></b> kill_sim</tt>

@section LEVEL2 Current Trick Version 

The following command echoes the installed %Trick version release:

<tt><b>UNIX Prompt></b> trick_version</tt>

@section LEVEL2 Checksumming

%Trick comes with a file that contains checksums for the %Trick package. You may run:

<tt><b>UNIX Prompt></b> trick_verify_checksums</tt>

at any time to see what, if any, files have changed from the original package. The checksum is
done on source files, not object code.


*/