@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@c 06.0.00 Building from Source: - - - - - - - - - - - - - - - - - - - - - - - -
@c         Compile the library   - - - - - - - - - - - - - - - - - - - - - - - -
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Building from Source
@unnumbered Building from Source
@cindex 06.0.00 Building from Source
@cindex source code

@section Tools

The @b{@t{AnsiCmd}} library and the @b{@t{EarthPoints}} test application 
are written in C++ and are built with the GNU C++ compiler and linker. 
No additional link libraries or third-party tools are needed.

@itemize @BSQUARE
@item GCC (G++) version 8 and above, (support for C++17 or greater).
@end itemize
@spi

@cindex compile from source
@section Compiling

The AnsiCmd library is compiled using the GNU/G++ compiler which is 
invoked through the 'gmake' ('make') utility. The compile and 
linking instructions are contained in the file named 'Makefile'. 

@example
Examples:
      gmake all
      gmake clean
      gmake
      gmake buildlib    # build the AnsiCmd library only
@end example
@spi

@cindex build options
@anchor{Build Options}
@section Build Options

Conditional compilation directives control the build options, both for the 
@t{AnsiCmd class} library and the @t{EarthPoints} application.

Four major conditional-compilation directives control most, if not all 
the sub-directives. The first is the @b{@t{INCLUDE_API}} directive which 
enables or disables inclusion of the high-level constructs related to 
the creation of window objects and user-interface controls.@*
The second is the @b{@t{DEBUG_ANSICMD_TEST}} directive which enables the 
test suite located in @t{AnsiCmdTest.cpp}.@*
The other two directives manage the debugging code embedded within the 
@t{AnsiCmd} library methods. These embedded tests are used to verify 
algorithm design and functionality for the library as a whole.@*
These are the @b{@t{DEBUG_ANSICMD}} and @b{@t{DEBUG_LOG}} directives. All 
other debugging code is designed to be subordinate to these. If these two 
are enabled, debugging code (other than the test suite) is potentially 
enabled. If these two directives are disabled, then all debugging code 
is disabled.

Because the @t{AnsiCmd class} as well as the @t{EarthPoints} application 
are primarily experimental in design, a large number of 
conditional-compilation directives are defined to assist in development 
and debugging of the code. The following is a list of the directives 
which persist beyond the immediate needs of the programming day.

Please @pxref{Development and Testing} for more information.

@Subsubheading{AnsiCmd Class Directives,
               ------------------------}

@enumerate 1
@item DEBUG_ANSICMD@*
This directive is defined in @b{@t{AnsiCmd.hpp}}, and is the master 
directive for all debugging code within the AnsiCmd class.@*
@verb{|    #define DEBUG_ANSICMD (1)|} debugging code is compiled.@*
@verb{|    #define DEBUG_ANSICMD (0)|} debugging code is excluded.

All other debugging directives in the AnsiCmd source code are nested 
within this directive. Setting the definition to zero @emph{SHOULD} 
disable all debugging code within the AnsiCmd class, @b{@emph{including}} 
all the testing methods (grouped under @t{DEBUG_ANSICMD_TEST}).

@item DEBUG_ANSICMD_TEST@*
This directive is defined in @b{@t{AnsiCmd.hpp}}, and controls whether the 
test suite is included in the library build. This directive should be enabled 
when linking with the @t{EarthPoints} application, so that all tests and 
diagnostic code will be available. The test suite is optional when linking the 
library with the other demo apps. If present, it will not affect the functionality 
of those apps; however, disabling the test suite will reduce the size of the 
compiled library by approximately 500Kb.

@item DEBUG_LOG@*
This directive is defined in @b{@t{AnsiCmd.hpp}}, and controls whether a log 
file will be created to contain miscellaneous debugging information.

If enabled (1), the file will be created in the source code directory with 
the name: @LDQ{}@b{@t{dbg.log}}@RDQ{}. If a file of that name already 
exists, it will be overwritten. The file is closed before the program exits.

The log file contains detailed data on the program execution sequence and 
the results of specific operations. For instance it can report configuration 
data or interim results of binary operations such as:@*
@verb{|   decode( fgIndex:04 hue:00 shade:00 r:0 g:0 b:0 )|}@*
@verb{|         ( bgIndex:02 hue:00 shade:00 r:0 g:0 b:0 )|}@*
@verb{|           ---r brfc --mods--- --bgnd--- --fgnd---|}@*
@verb{|          b0000-0000-0000-0111-0000-0010-0000-0100|}

@item Default Configuration@*
As distributed, the package should have @t{INCLUDE_API} directive, as well as the 
@t{DEBUG_ANSICMD}, @t{DEBUG_LOG} and @t{DEBUG_ANSICMD_TEST} directives enabled, 
which in turn enables the tests of library functionality in the @t{EarthPoints} 
application.@*
To verify this, after unpacking the archive, use the @t{'grep'} 
utility to display the debugging directives:@*
@b{@verb{!   grep -n '#define DEBUG_' *.[hc]pp | grep '[(]1[)]' !}}@*
@verb{|   |}@i{(This is why OCD is not really a @LDQ{}disorder@RDQ{} at all. :-)}

As a convenience, a small Perl utility, @t{'report.pl'} is included in 
the distribution archive. This utility will report the current state of the 
conditional-compile directives described above.@*
This utility is also invoked by the Makefile when performing a clean build:@*
@b{@verb{|      gmake all|}}

@item Embedded Debugging Directives@*
These directives may be enabled temporarily to verify intermediate states of 
data and execution flow for a particular section of the code. These directives 
typically affect only one method, or a small group of related methods. These 
directives may affect overall library functionality and so should be disabled 
when not being directly monitored.

@ifhtml
@sp 2
@end ifhtml

@hr20

@itemize @SSQUARE @c =============
@item DEBUG_CURPOS@*
@item DEBUG_SEQUENCE@*
These directives are defined within the @b{@t{acGetCursor}} method, in the 
@b{@t{AnsiCmd.cpp}} module.

The test code uses the debugging log file (see above) to report the 
transmission of the @t{ANSI} escape sequence commands and the capture 
of the response.

The @t{ANSI} escape sequence for @emph{get-cursor-position} is the most 
complex of the escape sequences defined by the standard. This is because 
after issuing the command, the response is returned to the application 
as an escape sequence via @t{'stdin'}. This opens the possibility of 
trashing the display.

For this reason, special attention is given to the algorithm used to 
capture the incomming data. @EMDASH It works, but keep an eye on it.

@item DEBUG_SOFTKEY@*
This directive is defined within the @b{@t{specialkeyDecode}} method, 
in the @b{@t{AnsiCmd.cpp}} module.

The test code uses the debugging log file (see above) to report the 
captured byte sequences, convert them to standard keycodes and determine 
whether the keycode belongs to the group of @LDQ{}@b{special}@RDQ{} 
i.e. cursor-control keys.

@item DEBUG_FI@*
Located in the @b{@t{acFlushIn}} method in @b{@t{AnsiCmd.cpp}} to verify 
terminal configuration flags for flusing the input stream.
@item DEBUG_BSR@*
Located in the @b{@t{breaksignalReceived}} method in @b{@t{AnsiCmd.cpp}},
this enables monitoring of the break signal (@t{Ctrl+C key}) capture and 
processing.
@item DEBUG_SSR@*
Located in the @b{@t{suspendsignalReceived}} method in @b{@t{AnsiCmd.cpp}},
this enables monitoring of the suspend signal (@t{Ctrl+Z key}) capture and 
processing.

@item DEBUG_skForm@*
This directive is defined within the @b{@t{init_skForm}} method, in the 
@b{@t{AnsiCmdWin.cpp}} module.

The test code uses the debugging log file (see above) to report the 
contents of the the skForm object's data members.

@item DEBUG_SHIFT_TEXT@*
This directive is defined within the @b{@t{shiftFieldText}} method, in the 
@b{@t{AnsiCmdWin.cpp}} module. This method implements block-shift of text 
within the target field.

@item DEBUG_skpInterRow@*
@item DEBUG_skpDeleteChar@*
These directives report intermediate processing of the @LDQ{}special@RDQ{} 
keycodes.

@item DEBUG_normalkeyProc@*
This directive reports intermediate processing of the @LDQ{}normal@RDQ{} 
(graphing) keycodes.

@item DEBUG_wpos2tpos@*
This directive is located in the @t{wpos2tpos} method which converts 
window-relative coordinates to terminal-relative coordinates. (currently unused)

@item DEBUG_SA@*
This directive is located in the @b{@t{acSetAttributes}} method and validates 
decoding of color-attribute bitfields and transmitting the corresponding @t{ANSI} 
escape sequences to set the attributes.

@item DEBUG_TERMSETUP@*
@item DEBUG_TS_PAUSE@*
These directives are defined in the @b{@t{ansicmdSetup}} method which parses 
command-line arguments related to terminal configuration.

@item DEBUG_EOTOFF@*
@item DEBUG_ipOffset@*
These directives are defined within the @t{eotOffset} and @t{ipOffset} methods, 
respectively, and report the interim results when calculating the cursor 
position within a field under edit.

@item DEBUG_RGB_WEB@*
This directive is defined within the @b{@t{trgbStepWeb}} method, in the 
@b{@t{AnsiCmdTest.cpp}} module.

This method displays the supported @LDQ{}web-safe@RDQ{} colors by setting 
the background color attribute. The directive is used to temporarily 
render the web-safe colors by setting the @emph{foreground} instead of the 
background.

@item DEBUG_TestWindow@*
This directive is defined within the @b{@t{Test_Window}} method, in the 
@b{@t{AnsiCmdTest.cpp}} module. (currently unused)

@item DEBUG_TEXTBOX@*
This directive is defined within the @b{@t{ddzCallback}} method, in the 
@b{@t{AnsiCmdTest.cpp}} module. This is the callback method which monitors 
real-time user interaction within an ACDlg class window@EMDASH{}specifically 
for testing scrolling of text data within a field.

@item DEBUG_TFBDR@*
This directive is defined within the @b{@t{Test_Form}} method, in the 
@b{@t{AnsiCmdTest.cpp}} module. Optionally test field outline for 
Radiobutton controls.(currently unused)

@item DEBUG_ACWCB@*
This directive is defined at the top of the @b{@t{AnsiCmdApi.cpp}} module. 
Report the intermediate results of interaction with the system clipboard.

@item DEBUG_decode@*
@item DEBUG_update@*
@item DEBUG_modify@*
@item DEBUG_compose@*
@item DEBUG_swap@*
@item DEBUG_buildRgb@*
@item DEBUG_build8bit@*
This group of directives manages debugging information for the acaExpand class 
which is used to encode, decode and apply color-attribute data.
@end itemize @c SSQUARE

@item INCLUDE_API@*
This directive controls compilation of methods and data for the high-level 
functionality of the @t{AnsiCmd} library.

The @t{API} methods are used by the @t{EarthPoints} application for 
optional output of the coordinate reports to an @t{ACWin-class} object; however, 
@t{EarthPoints} will build successfully even when this directive is disabled 
(set to zero). But in this case, the windowed output option will not be available.

The @t{API} methods are required by the @t{AcEdit} application which 
integrates both @t{ACWin-class} and @t{ACDlg-class} objects into the 
application design.

The @t{API} methods are not used in the CsvView application which is 
implemented using only the low-level @t{AnsiCmd} methods.

Therefore, when building the @t{AnsiCmd} library, keep in mind the application 
to which the library will be linked, and set or reset this directive as needed.

@cindex clipboard directive
@cindex directive, clipboard
@itemize @SSQUARE
@item INCLUDE_WAYLANDCB@*
This is a sub-directive under control of the @t{INCLUDE_API} directive 
and is defined in @b{@t{AnsiCmd.hpp}}.@*
The @t{INCLUDE_API} directive enables the @b{@emph{local clipboard}} which 
is available only within the application itself.@*
When @t{INCLUDE_WAYLANDCB} is enabled, access to the Wayland (system) 
clipboard becomes available through the WaylandCB class, assuming the 
connection with the system can be established.@*
The system clipboard connection requires installation of the Linux utility:
@t{'wl-clipboard'}.@*
@verb{|   sudo dnf install 'wl-clipboard'|}@*
@verb{|   sudo apt-get install 'wl-clipboard'|}@*
For details, please see the documentation included as part of the standalone 
@t{WaylandCB} package.@*
(@xref{By the Same Author}.)@*
Please @pxref{AnsiCmd Clipboard Access} which describes the clipboard 
interaction methods.
@end itemize
@end enumerate

@indentedblock
@Subsubheading{ACWin-class and ACDlg-class Directives,
               --------------------------------------}

Within the @t{API} group of methods, some additional directives are defined. 
All debugging directives in this group are contained within the global 
@t{DEBUG_ANSICMD} directive, so disabling this global debugging directive will 
also disable all @t{API} debugging code.

@itemize @SSQUARE
@item DEBUG_WDUMP @EMDASH enable write of config data to log
@item DEBUG_FDUMP @EMDASH enable write of field data members to log
@item DEBUG_MDUMP @EMDASH enable write of field MRParse data to log
@item DEBUG_FIFO @EMDASH enable write of BlockFifo data to log
@item DEBUG_PHOTO @EMDASH enable screenshot (for documentation)@*
These directives are defined within the @b{@t{AnsiCmdWin.hpp}} module and 
control output of various groups of @t{ACWin} configuration information 
to the debugging log file.
@item DEBUG_PHOTO2 @EMDASH located in the @b{@t{Screenshot}} method. 
Supports screenshot capture.
@ifhtml
@sp 2
@end ifhtml

@item DEBUG_KPUSH @EMDASH enable support methods of KeycodePush group
@item DEBUG_GFD @EMDASH request copy of skField data structure
@item DEBUG_PFT @EMDASH parsing algorithm for field text
@item DEBUG_SKP @EMDASH special-key processing for 'flowing' text
@item DEBUG_skpST @EMDASH special-key processing for 'shifted' text
@item DEBUG_skpInterRow @EMDASH calculate inter-row offset
@item DEBUG_DELCHAR @EMDASH algorithm for deleting a character
@item DEBUG_NKP @EMDASH filter and process 'normal' keycodes@*
These directives are defined within the @b{@t{AnsiCmdWin.cpp}} module and 
are related to identification and processing of @LDQ{}special@RDQ{} 
keycodes received from the user.
@ifhtml
@sp 2
@end ifhtml

@item DEBUG_CBGET_FLOW @EMDASH paste to control with 'flowing' text
@item DEBUG_CBGET_SHFT @EMDASH paste to control with 'shifting' text
@item DEBUG_CBGET_OVER @EMDASH overflow of field during paste@*
These directives are defined within the @b{@t{AnsiCmdSkf.cpp}} module and 
are used to validate the functionality of the local clipboard @LDQ{}paste@RDQ{} 
operation for Textbox fields.
@ifhtml
@sp 2
@end ifhtml

@item DEBUG_skForm @EMDASH range-check top-level skForm members
@item DEBUG_IMF @EMDASH verify array of skField objects
@item DEBUG_IMM @EMDASH validate data for Menubox controls
@item DEBUG_ISB @EMDASH validate data for Scrollbox controls@*
These directives are defined within the @b{@t{AnsiCmdSkf.cpp}} module and 
validate initialization of the @b{@t{skForm}} and @b{@t{skField}} objects.
@ifhtml
@sp 2
@end ifhtml

@item DEBUG_CCFG @EMDASH 
@item DEBUG_SB @EMDASH 
@item DEBUG_MB @EMDASH 
These directives are defined within the @b{@t{AnsiCmdSkf.cpp}} module and 
validate per-row color attribute configuration for Menu and Scrollbox 
controls.
@ifhtml
@sp 2
@end ifhtml

@item DEBUG_SA @EMDASH color attribute bitfield initialization
@item DEBUG_TERMSETUP @EMDASH display terminal setup options
@item DEBUG_TS_PAUSE @EMDASH after report, pause for user response@*
These directives are defined within the @b{@t{AnsiCmdApi.cpp}} module and
validate terminal window color-attribute initialization and parsing of 
command-line parameters for terminal configuration, respectively.
@ifhtml
@sp 2
@end ifhtml

@item DEBUG_QDialog@*
This directive is defined within the @b{@t{AnsiCmdDlg.cpp}} module and 
validates configuration of the @ref{QuickDialog} invocation.
@ifhtml
@sp 2
@end ifhtml

@item DEBUG_Dialog
@item DEBUG_ADJ@*
These directives are defined within the @b{@t{AnsiCmdDlg.cpp}} module and 
validate configuration of the full-initialization dialog.
@ifnothtml
@*
@end ifnothtml
@ref{Dialog} invocation.
@ifhtml
@sp 2
@end ifhtml

@item DEBUG_ED_CLIP@*
This directive is defined within the @b{@t{AnsiCmdDlg.cpp}} module and 
monitors user interaction within the @t{editDialog} method.
@end itemize @c SSQUARE
@end indentedblock
@sp 1

@Subsubheading{EarthPoints Application Directives,
               ----------------------------------}

@enumerate 1
@item DEBUG_EPNTS@*
This directive is defined in the @b{@t{EarthPoints.hpp}} module.@*
It controls debugging code specifically designed to test parsing of 
GPS data and calculation of arc distances.

@item DEBUG_PARSE@*
This directive is defined in the @b{@t{EarthPoints.hpp}} module.@*
It controls debugging code for parsing the user's command line input.

@item DEBUG_PVALUE@*
This directive is defined in the @b{@t{EarthPoints.hpp}} module.@*
It controls debugging code for parsing GPS values in degrees and radians.

@item DEBUG_VERBOSE@*
This directive is defined in the @b{@t{EarthPoints.hpp}} module.@*
As the name implies, it enables additional debugging information for 
verification of data operations.

@item DEBUG_GCLA@*
This directive is defined within the @b{@t{GetCommandLineArgs}} method, in 
the @b{@t{EpParse.cpp}} module.

The results of parsing the command-line arguments are written to the 
terminal window, and the application then waits for the user to press 
the ENTER key before continuing program execution.
@end enumerate

@cindex test the build
@section Testing the Build

To test the build, invoke with a request for the EarthPoints version number. 
You should get something similar to the following:

@example
./epts --version

EarthPoints (epts) v:@ACVERSION Copyright(c) @CRYEARS  The Software Samurai
========================================================================
License GPLv3+: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>
This is free software: you are free to modify and/or redistribute it
under the terms set out in the license.
There is NO WARRANTY, to the extent permitted by law.
@end example
@spi

@cindex info database
@cindex documentation, installing
@anchor{installing the documentation}
@Subheading{Installing the Documentation,----------------------------}

Documentation for the @t{AnsiCmd} library is provided in both Texinfo (info) 
format and HTML format.

To view the HTML-format documentation, navigate to:@*
@verb{|    AnsiCmd/Texinfo|}@*
then load the @verb{|'ansicmd.html'|} document into your favorite browser. 
Note that the @verb{|'infodoc-styles.css'|} CSS style definition file 
must be in the same directory as the HTML document.

To view the Texinfo (info) documentation, navigate to:@*
@verb{|    AnsiCmd/Texinfo|}@*
then view the documentation using the following command:@*
@verb{|    info -f ansicmd.info|}

Follow these steps to install the @t{AnsiCmd} documentation into the 
@LSQ{}info@RSQ{} database.

@enumerate 1
@item Note that installing the documentation is not necessary, but is 
recommended. Not only is it convenient to have the documentation always 
available, but it is a useful skill for when you begin installing 
documentation for your own applications!

@item Adding an @LSQ{}info@RSQ{} document to the info-reader database (or 
removing a document from the database) is easy, but it does require 
@LSQ{}@i{SUPERUSER}@RSQ{} (@LSQ{}root@RSQ{}) user privilege. If this makes 
you nervous, please make a backup copy of the @LSQ{}dir@RSQ{} 
(info directory) file before modifying it.

@item Open a terminal window.

@item Navigate to the directory which contains the @t{'ansicmd.info'} 
documentation.

@example
Example:
  @b{cd ~/MySoftware/AnsiCmd/Texinfo}

  (substitute your actual installation path)
@end example

@item Locate the master Info system directory file: 'dir'.@*
For local users, this is typically:@*
@verb{|      /usr/local/share/info/dir|}

For global system users, this is typically:@*
@verb{|      /usr/share/info/dir|}

@item Copy the document to the directory where you found the info 'dir' file.
@example
Example:
@b{sudo cp @minus{}@minus{}preserve=timestamps ansicmd.info /usr/local/share/info/.}

(substitute the actual path to the directory containing the 'dir' file)
Enter your password when prompted.
@end example

@item Navigate to the Info target directory.@*
@verb{|      cd /usr/local/share/info|}

@item Verify that the document was copied correctly.@*
@verb{|      ls -l ansicmd.info|}

@item Add the menu entry.
@example
@b{sudo install-info 
        @minus{}@minus{}dir-file=dir @minus{}@minus{}info-file=ansicmd.info 
        @minus{}@minus{}name='AnsiCmd-class Library' @minus{}@minus{}debug}

Note that this is a single command, typed all on one line 
even though it may look strange as printed here.

Enter your password when prompted.
@end example

@item Verify the install.
@example
Type the following command:
   @b{info}
@end example

This will open the top-level menu of the Info system.@*
Verify that your new entry is beautifully displayed and that 
the new Info document is accessible:

First, press the forward-slash key @verb{|'/'  |}(search)@*
Then, type:  AnsiCmd-class Library@verb{|       |}(and press ENTER)@*
The highlight should now be on the menu entry.@*
Press ENTER (RET) key again, and verify that the main page of the AnsiCmd 
documentation is displayed.@*
Then, exit the Info system: @t{'q'} (quit).

@item
If the menu item is not present OR if the new Info document is not accessible, 
then try the installation again.

If you want to remove the menu entry, use the command:
@example
@b{sudo install-info 
    @minus{}@minus{}dir-file=dir @minus{}@minus{}info-file=ansicmd.info
    @minus{}@minus{}name='AnsiCmd-class Library' @minus{}@minus{}remove @minus{}@minus{}debug}
    
Again, this is a single command, typed all on one line.

Enter your password when prompted.
@end example
@end enumerate
@sp 2


