*   writing COMPLETE C++ programs

*   we've been writing C++ functions - but not (directly) writing
    C++ PROGRAMS;

    *   a C++ program is a collection of functions, exactly one
        of which has the name main 

    *   this main function has to have one of a few headers --
        we'll use the simplest:

        int main()

    *   you link together all the compiled functions to create an
        executable file --- an executable program ---

        and when you run this program, it begins by executing main.

        *   how might you run it? Type the name of the executable
            file at a UNIX prompt, double-click on the executable
            file in a GUI (graphical user interface) environment, 
            select a run command within some
            menu of an Integrated Development Environment (IDE)

*   so, the main function is the "controller" for a C++ program ---
    it gets everything started;

*   what's the int for? (int main())

    *   it is to permit the main to return a value telling the caller
        (the operating system or perhaps a shell script) whether it
        executed successfully or not;

    *   ...and the "success" value is different for some different
        operating systems!

    *   SO: there is an already-defined named constant, EXIT_SUCCESS,
        in C++ that you can use and KNOW will be the proper value
        when your code is compiled.

    *   so, COURSE STYLE STANDARD:
        ...thou shalt end your main function with:

        return EXIT_SUCCESS;

        *   (you can return EXIT_FAILURE for programs where you know
            you are ending unsuccessfully, if you wish... not required
            for CIS 130)

*   a main function almost always uses SOME kind of input or output;
    and that means accessing at least one C++ library, since input/output
    is not part of the "core" C++ language;

    *   so: how do you access those libraries?

    *   using #include

*   #include is a PRECOMPILER DIRECTIVE

    ...done BEFORE actual compiling;

    they are done, THEN the resulting code is COMPILED/translated;

    *   #include in particular literally includes the contents of
        the specified file INTO your file before compiling it;

    *   two main forms (in modern C++):

        if you want to include a C++ standard library, you
        put:

        #include <name_of_lib>
        using namespace std;

        *   (we'll be using the std, or standard, default namespace)

        *   so, to include the needed stuff for cin and cout,
            you need the iostream library, and so you'd have:

            #include <iostream>
            using namespace std;

        *   do note: you can #include as many libraries, or even
            header files, as you want; each gets its own #include

            C++ cmath library has goodies like sqrt, round,  
            etc; if you wanted to use those functions as well
            as cin, cout, etc, then you'd have:

            #include <iostream>
            #include <cmath>
            using namespace std;

    *   the OTHER form of #include is for HEADER files for
        functions you have written yourself ---

        *   note that you include header, or .h, files, instead
            of the code itself;

        *   (don't #include .cpp files, you are too likely to
            doubly-define something, which is a syntax error in C++)

        *   this form, for including a function named my_funct, would
            be:

            #include "my_funct.h"
            using namespace std;

	    or, more likely,

	    #include <iostream>
            #include "my_funct.h"
            using namespace std;

*   so, a C++ main "template" could look like this:

    (and this will also be available from public course web page:)

/*
  contract: main: void -> int
  purpose: either describe the program's purpose OR
           testing program for function <f>
  examples: describe what it does

  by: <your name>
  last modified: last-modified date
*/

#include <iostream>
using namespace std;

int main()
{
    ... program actions ...

    return EXIT_SUCCESS;
}

*   you'll note that Dev-C++ provides much of this skeleton, also;

    open Dev-C++,
    under File menu, select File->New->Project

    in the New Project window, select "Console Application"

 
            (Dev-C++ is an IDE, for example...)

*   for a non-main function, in its own file, the C++
    convention is to put it in a file based on the function
    ...so, ring_area would be in a file ring_area.cpp

    BUT!! every program has its own main, so NOT a good idea
    to put it in main.cpp --- you'd overwrite another main
    eventually!

    SO: the C++ convention for a main function is to put it
    in a file with the name you'd like to use for the overall
    program.... 

    so, for a program testing ring_area, I might put the main in
    test_ring_area.cpp

*   what if you want to type your own header file (.h file)
    for a function?

    *   note: the main function DOESN'T need a header file!
        ...it's the "top" piece;

    *   here's the template for a header file for non-main 
        function named blah

/*
   header file for function: blah
   name: your name
   last modified date: date
*/

#ifndef BLAH_H
#define BLAH_H

const type BLAH_CONST = value; 

blah's header followed by a semicolon;

#endif

*   and, if a named constant used in function a is possibly useful to 
    other functions that call function a,

    then it is useful to declare that named constant in the header
    file for function a, a.h

    (then when a function #include's a.h, then it also can now use
    the named constant defined there)

*   THEN, as mentioned in an earlier lab, to compile a file of C++ functions
    into an object file,

    g++ -c anyfile.cpp

    ...will compile ANY C++ function, putting the resulting object
    code (if successful!) into anyfile.o

*   AND: to create an executable C++ program?

    *   leave off the -c option

    *   add the -o desired_executable option

    *   include the .o files for EVERY function INVOLVED in this program

    g++ -o desired_executable desired_executable.o called1.o called2.o

    *   NOTES:
        *   CAN do compiling and linking in one step --- put files with
            .cpp instead of .o. 

            (but separate compilation makes it more obvious which
            file a syntax error is in...)

        *   -o executable_result can go anywhere, BUT executable
            name desired must IMMEDIATELY follow the -o!

        *   if omit the -o option, executable goes in a file named
            a.out

        *   C++ (and C) tradition: call the executable the same name
            as the file main is in, WITHOUT the suffix.

        *   DON'T omit the executable name after the -o! If you do
            and put the source code file after --- oops, it happily
            deletes the contents of the source code file! OUCH!!!