README file for 'Salmon'.

Copyright 2012-2026 by The Software Samurai.
On the web:  http://www.SoftwareSam.us/
Software released under GNU GPL3, and documentation released under FDL1.3
=========================================================================

-- =========================================
--              Introduction               =
-- =========================================

This package contains source code and documentation for the 'Salmon' application.

You will need to build the source and target application binaries for your 
target system (see below).

The 'Salmon' application is a GNU/Linux console (command-line) utility which 
demonstrates some common examples of spawing an external process from within 
an application.

Version history for the application can be found in the header of Salmon.cp.

This application is intended as a reference for students and others who want 
to understand the use of the "exec" group of C-language primitive functions 
and other functions related to spawing a child process from within a parent 
application.

The Salmon package includes source code for two executable binary files, 
'Salmon' and 'childApp'. Salmon contains the interesting code which invokes 
childApp with various arguments. childApp simply reports the arguments it has 
received from the controlling application, then termnates.

We apologize for the application name, but we couldn't resist. 
This project was written strictly for fun. "Salmon" swim upstream to spawn fish 
eggs, not process IDs, but we hope you get the idea.
  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

-- =========================================
-- NOTES on the current release of Salmon  =
-- =========================================

-- Build requires the GNU C++ compiler, version 8.1 or higher. 
   Current development version is v:15.2.1 20260123 (Red Hat 15.2.1-7)
   -- FULL C++17 SUPPORT IS REQUIRED for a successful build.

-- Rebuilding the Texinfo documentation requires 'makeinfo' (texi2any) v:6.8 
   or greater (v:7.2 recommended).

-- Rebuilding the HTML documentation requires the 'idpp' post-processor 
   utility, which is part of the 'Infodoc' package (v:0.0.16) available 
   for download on the author's website. 

-- Current Release
   -- This demonstration app was originally designed as a classroom project; 
      however, the previous release was in late 2019, and one or two interesting 
      things have happend in the programming world since then.
      The application has been updated from a C-language hack to _almost_ reach 
      the level of a real application.
      -- Minor updates have been made for all test options; specifically, 
         the C-language string manipulation functions have been replaced by 
         the author's gString class which supports text formatting and analysis 
         with much less code clutter or danger of buffer overruns.
      -- The only major change for the application is for test '-t' which opens 
         a new terminal window for 'gnome-terminal', 'konsole', or 'xterm'.

   -- In honor of the above changes, the documentation has been transitioned from
      a simple README file to an actual Texinfo/HTML document (source included).

   -- Programmers always believe that our work is totally bug-free, and we 
      are always wrong. Please report all bugs or suspected bugs via the 
      website.

   The files included in this release.
   -----------------------------------
   Salmon/            // Source code directory
      Salmon.hpp      // Definition of the Salmon class
      Salmon.cpp      // Main demonstration application
      childApp.cpp    // Secondary application invoked by the child process
      GlobalDef.hpp   // '#include' files and general definitions
      gString.hpp     // Definition of the gString class for text analysis
      gString.cpp     // gString class for text formatting and analysis
      Makefile        // Build the 'salmon' application
      README          // Package description, release notes (this file)
      /Texinfo        // Documentation
         Salmon.texi          // Documentation source code (Texinfo format)
         salmon.info          // Documentation in 'info' format
         salmon.html          // Documentation in HTML format
         infodoc-styles.css   // CSS style definition required by the HTML documentation
         gStringTextTool.texi // Documentation source for gString class
         texi_macros.texi     // General macro definitions for creating Texinfo documents
         same_author.texi     // Boilerplate for Software Sam's published software
         gpl-3.0.texi         // GNU General Public License text (from FSF)
         fdl-1.3.texi         // GNU Free Documentation License text (from FSF)
         Makefile             // Build the info and HTML documents

   To read the full Texinfo documentation for this package, type: 
                      info -f salmon.info
   or even better, open the 'salmon.html' file in your favorite browser.
  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

-- ======================================
-- Building the 'Salmon' applications:  =
-- ======================================

   Building the applications from source:

   1) Open a terminal window of a convenient size. 
      The application should _build_ in any terminal emulator window; however, 
      application functionality testing has been done only in 'gnome-terminal', 
      'konsole' and 'xterm'.

   2) Verify that your compiler is at least version 8.1:
            g++ --version

            g++(GCC) 15.2.1 20260123 (Red Hat 15.2.1-7)
            Copyright (C) 2025 Free Software Foundation, Inc.

      If you are not using GCC, then verify that your compiler fully supports 
      the C++17 standard.

   3) Download the Salmon archive and copy it to the directory where your 
      software projects live:
            cp --preserve=all salmon-0.0.05.tar.bz2 ~/SoftwareDesign
            cd ~/SoftwareDesign

   4) Unpack the archive.
      The Salmon directory will be created and all source files will be expanded 
      into that directory.
            tar -xjvf salmon-x.x.xx.tar.bz2

   5) Navigate to the source directory:
            cd Salmon

   6) Build both the main application and the target application:
            gmake all

      When both applications build without errors and without warnings, 
                           CONGRATULATIONS!

   7) Test the primary application:
            ./salmon --version

      The application version number and copyright information 
      should be displayed.

   8) Test the primary application:
            ./salmon -v

      You should see something like the following, indicating that both 
      applications are functioning properly:

      Salmon Swim Upstream To Spawn!
       Invocation: './salmon -v'
       Parent PID: 8592
       calling execv( childApp argv[] )
      
            childApp: PID: 8592
            ====================
            argv[0] childApp
            argv[1] -v
            argv[2] Types of Salmon:
            argv[3] Trout
            argv[4] Char
            argv[5] Grayling
            argv[6] Whitefish
            
            [Salmon]$ 


-- ============================
-- Known bugs and other issues:
-- ============================
   -- Terminal emulator and shell program configuration are system dependent, 
      which may affect output formatting and/or creation of secondary terminal 
      windows.
   -- No outstanding bug reports.

