trunk/c_vct0/c_vct0.tex

%$Header: /uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions/c_vct0.tex 3     12/31/00 7:42p Dashley1 $

\chapter{\cvctzerolongtitle{}}

\label{cvct0}

\beginchapterquote{``\ldots{} Beauty is the first test:  there is no permanent
                   place in the world for ugly mathematics.''}
                   {G.H. Hardy \cite{bibref:b:mathematiciansapology:1940},
                   p.85}

\section{Introduction}
%Section Tag: INT
This chapter documents the Tcl/Tk extensions present in IjuScripter and IjuConsole
designed to allow a script to determine the version of IjuScripter or IjuConsole under
which it is running.  At present, there is only one such command, \emph{vcinfo}.


\section{vcinfo}

\begin{tclcommandname}{vcinfo}%
retrieves embedded static version and version control information for IjuScripter or IjuConsole.
This allows a script to determine which executable and which version it is
running under.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{vcinfo}{-ijutoolsversion}
\tclcommandsynopsisline{vcinfo}{?-crconly? -fileversion filename}
\tclcommandsynopsisline{vcinfo}{?-crconly? -extensionversion extensionname}
\tclcommandsynopsisline{vcinfo}{-buildmanifest}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{vcinfo} command returns information about the version of the
IjuScripter or IjuConsole executable program, about the version of
a specific source file, or [collectively] about the version of all files
which [directly] contribute to the behavior of an embedded Tcl extension.
This command can be used to interactively
inquire about the version of the executable program or certain of its
components.

Most commonly, this command is used to help assure reproducibility
of a script's behavior by coding a script so that it will
run only under a specific version(s) of executable.

\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-ijutoolsversion}}
Returns a string identifying the version number of the IjuScripter or IjuConsole
executable.  The string will be of the form ``vm.nx'', where \emph{v} is the letter
``v'', \emph{m} is the major version number, \emph{n} is the minor version number, and 
\emph{x} is an optional lower-case letter identifying a service release which fixes defects
but adds no new functionality.

For example, a return value of ``v1.03'' would identify version 1.03.  A return
value of ``v1.03c'' would identify the third service release to version 1.03; with
the service release designed to correct defects present in version 1.03b, but adding
no new functionality.
\end{tclcommandinternaldescription}

\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-fileversion filename}}
(Not yet implemented.)  Returns a string with version control information for the file 
\emph{filename}, which must be part of the IjuScripter or IjuConsole build.
An error is generated if a \emph{filename} which is not part of the build
is supplied.  This form of the \emph{vcinfo} command is not normally used from a script.
\end{tclcommandinternaldescription}

\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-crconly -fileversion filename}}
(Not yet implemented.)  Returns the CRC32 of the the string result of the command above.  
Note that the value returned is the CRC of the version control information embedded in the file
rather than the CRC of the file.
\emph{filename} must be part of the IjuScripter or IjuConsole build, and 
an error is generated if a \emph{filename} which is not part of the build is supplied.
This form is
useful because it supplies a terse result of eight hexadecimal digits which can easily
establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole
have the same file component; or establish with unity probability that they do not.
\end{tclcommandinternaldescription}

\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-extensionversion extensionname}}
(Not yet implemented.)  Returns a string with version control information for all
files which contribute directly to the behavior of the Tcl extension \emph{extensionname}, 
which must be part of the IjuScripter or IjuConsole static build.
An error is generated if an \emph{extensionname} which is not part of the build
is supplied.
\end{tclcommandinternaldescription}

\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}
      {-crconly -extensionversion extensionname}}
(Not yet implemented.)  Returns the CRC32 of the the string result of the command above.  
Note that the value returned is the CRC of the version control information embedded in the file(s)
rather than the CRC(s) of the file(s).
\emph{extensionname} must be part of the IjuScripter or IjuConsole build, and 
an error is generated if an \emph{extensionname} which is not part of the build is supplied.
This form is
useful because it supplies a terse result of eight hexadecimal digits which can easily
establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole
have the same extension component; or establish with unity probability that they do not.
\end{tclcommandinternaldescription}

\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-crconly -buildmanifest}}
(Not yet implemented.)  Returns the full combined build manifest of IjuScripter and IjuConsole.
This includes size and CRC information for every file involved in the build.  This form
of \emph{vcinfo} is provided for assistance in defect diagnosis.
\end{tclcommandinternaldescription}

\end{tclcommanddescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\noindent\begin{figure}[!b]
\noindent\rule[-0.25in]{\textwidth}{1pt}
\begin{tiny}
\begin{verbatim}
$Workfile: c_vct0.tex $
$Archive: /uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions/c_vct0.tex $
$Revision: 3 $
$Author: Dashley1 $
$Date: 12/31/00 7:42p $
$Modtime: 12/24/00 2:59a $
\end{verbatim}
\end{tiny}
\noindent\rule[0.25in]{\textwidth}{1pt}
\end{figure}

%$History: c_vct0.tex $
% 
% *****************  Version 3  *****************
% User: Dashley1     Date: 12/31/00   Time: 7:42p
% Updated in $/uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions
% 
% *****************  Version 2  *****************
% User: Dashley1     Date: 12/22/00   Time: 12:57a
% Updated in $/uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions
% Tcl automated method of build refined.
% 
% *****************  Version 1  *****************
% User: David Ashley Date: 11/29/00   Time: 7:14p
% Created in $/uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions
% Initial check-in.
%
%End of file C_VCT0.TEX
1	dashley	5	%$Header: /uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions/c_vct0.tex 3 12/31/00 7:42p Dashley1 $
2
3			\chapter{\cvctzerolongtitle{}}
4
5			\label{cvct0}
6
7			\beginchapterquote{``\ldots{} Beauty is the first test: there is no permanent
8			place in the world for ugly mathematics.''}
9			{G.H. Hardy \cite{bibref:b:mathematiciansapology:1940},
10			p.85}
11
12			\section{Introduction}
13			%Section Tag: INT
14			This chapter documents the Tcl/Tk extensions present in IjuScripter and IjuConsole
15			designed to allow a script to determine the version of IjuScripter or IjuConsole under
16			which it is running. At present, there is only one such command, \emph{vcinfo}.
17
18
19			\section{vcinfo}
20
21			\begin{tclcommandname}{vcinfo}%
22			retrieves embedded static version and version control information for IjuScripter or IjuConsole.
23			This allows a script to determine which executable and which version it is
24			running under.
25			\end{tclcommandname}
26
27			\begin{tclcommandsynopsis}
28			\tclcommandsynopsisline{vcinfo}{-ijutoolsversion}
29			\tclcommandsynopsisline{vcinfo}{?-crconly? -fileversion filename}
30			\tclcommandsynopsisline{vcinfo}{?-crconly? -extensionversion extensionname}
31			\tclcommandsynopsisline{vcinfo}{-buildmanifest}
32			\end{tclcommandsynopsis}
33
34			\begin{tclcommanddescription}
35			The \emph{vcinfo} command returns information about the version of the
36			IjuScripter or IjuConsole executable program, about the version of
37			a specific source file, or [collectively] about the version of all files
38			which [directly] contribute to the behavior of an embedded Tcl extension.
39			This command can be used to interactively
40			inquire about the version of the executable program or certain of its
41			components.
42
43			Most commonly, this command is used to help assure reproducibility
44			of a script's behavior by coding a script so that it will
45			run only under a specific version(s) of executable.
46
47			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-ijutoolsversion}}
48			Returns a string identifying the version number of the IjuScripter or IjuConsole
49			executable. The string will be of the form ``vm.nx'', where \emph{v} is the letter
50			``v'', \emph{m} is the major version number, \emph{n} is the minor version number, and
51			\emph{x} is an optional lower-case letter identifying a service release which fixes defects
52			but adds no new functionality.
53
54			For example, a return value of ``v1.03'' would identify version 1.03. A return
55			value of ``v1.03c'' would identify the third service release to version 1.03; with
56			the service release designed to correct defects present in version 1.03b, but adding
57			no new functionality.
58			\end{tclcommandinternaldescription}
59
60			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-fileversion filename}}
61			(Not yet implemented.) Returns a string with version control information for the file
62			\emph{filename}, which must be part of the IjuScripter or IjuConsole build.
63			An error is generated if a \emph{filename} which is not part of the build
64			is supplied. This form of the \emph{vcinfo} command is not normally used from a script.
65			\end{tclcommandinternaldescription}
66
67			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-crconly -fileversion filename}}
68			(Not yet implemented.) Returns the CRC32 of the the string result of the command above.
69			Note that the value returned is the CRC of the version control information embedded in the file
70			rather than the CRC of the file.
71			\emph{filename} must be part of the IjuScripter or IjuConsole build, and
72			an error is generated if a \emph{filename} which is not part of the build is supplied.
73			This form is
74			useful because it supplies a terse result of eight hexadecimal digits which can easily
75			establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole
76			have the same file component; or establish with unity probability that they do not.
77			\end{tclcommandinternaldescription}
78
79			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-extensionversion extensionname}}
80			(Not yet implemented.) Returns a string with version control information for all
81			files which contribute directly to the behavior of the Tcl extension \emph{extensionname},
82			which must be part of the IjuScripter or IjuConsole static build.
83			An error is generated if an \emph{extensionname} which is not part of the build
84			is supplied.
85			\end{tclcommandinternaldescription}
86
87			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}
88			{-crconly -extensionversion extensionname}}
89			(Not yet implemented.) Returns the CRC32 of the the string result of the command above.
90			Note that the value returned is the CRC of the version control information embedded in the file(s)
91			rather than the CRC(s) of the file(s).
92			\emph{extensionname} must be part of the IjuScripter or IjuConsole build, and
93			an error is generated if an \emph{extensionname} which is not part of the build is supplied.
94			This form is
95			useful because it supplies a terse result of eight hexadecimal digits which can easily
96			establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole
97			have the same extension component; or establish with unity probability that they do not.
98			\end{tclcommandinternaldescription}
99
100			\begin{tclcommandinternaldescription}{\tclcommanddescsynopsisline{vcinfo}{-crconly -buildmanifest}}
101			(Not yet implemented.) Returns the full combined build manifest of IjuScripter and IjuConsole.
102			This includes size and CRC information for every file involved in the build. This form
103			of \emph{vcinfo} is provided for assistance in defect diagnosis.
104			\end{tclcommandinternaldescription}
105
106			\end{tclcommanddescription}
107
108			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
109			\noindent\begin{figure}[!b]
110			\noindent\rule[-0.25in]{\textwidth}{1pt}
111			\begin{tiny}
112			\begin{verbatim}
113			$Workfile: c_vct0.tex $
114			$Archive: /uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions/c_vct0.tex $
115			$Revision: 3 $
116			$Author: Dashley1 $
117			$Date: 12/31/00 7:42p $
118			$Modtime: 12/24/00 2:59a $
119			\end{verbatim}
120			\end{tiny}
121			\noindent\rule[0.25in]{\textwidth}{1pt}
122			\end{figure}
123
124			%$History: c_vct0.tex $
125			%
126			% *************** Version 3 ***************
127			% User: Dashley1 Date: 12/31/00 Time: 7:42p
128			% Updated in $/uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions
129			%
130			% *************** Version 2 ***************
131			% User: Dashley1 Date: 12/22/00 Time: 12:57a
132			% Updated in $/uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions
133			% Tcl automated method of build refined.
134			%
135			% *************** Version 1 ***************
136			% User: David Ashley Date: 11/29/00 Time: 7:14p
137			% Created in $/uC Software Multi-Volume Book (A)/Chapter, VCT0, Version Control Extensions
138			% Initial check-in.
139			%
140			%End of file C_VCT0.TEX