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	%$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