make - advice.txt  -  some pointers for managing projects in Q'Nial with my make files etc
Bill Howell  draft ??Jun07


#******************************

Unfortunately, the operating system interface does NOT work in Q'Nial 6.3,
so normal Unix make capabilities are not possible!



#*********************************
   debugging tricks  (!!! OUT OF DATE !!!)


#  'Make' error location
1.  open 'make.ndf' in the QNial environment (as a separate window)
    a. in make.ndf set loaddef_mode := l  ;  autolog_mode := l  ;   symbol_mode  := l  ; 
    b. clearws
 											%  ; 
2.  type 'make "all' in the QNial interpreter window
    a. from the interpreter window:  Menu Interpreter -> view log file 
    b. Menu Search -> Find '?' -  follow the interpreter comments
    c. As QNial only flags the first error for each block, so this has to be done iteratively
    d. Use 'Symbol_list.txt' to refer to the source and application of global data and operations
       (but not local variables within blocks)
											%  ; 
3.  When errors are down to one file (or even before), you can focus on debugging it 
    by typing 'make f3' in the interpreter, for example (look at the list of files above 
    for their designations).

						
#   Progressive tesing of operations & data - once the 'make' errors are resolved
    This should eventually be converted to an automated check file that tests the results 
    against standard results and puts out error diagnostics.
											%  ; 
Note:  'command' means type the indicated string into the cQNial interpreter, (top level)
											%  ; 
1.  'Make all results.txt'  Raw data checks
    a. type ' Milancovic_rows  Milankovic_cols ' then 'Milankovc ' - are they correct?
       All 'raw' data can be checked by looking through the saved file 'Make all results.txt'
    b. Do the same with  'Solanki' 'Solanki_rows'  'Solanki_cols' 
#
2.  'complete_inputs verification.txt' 
    Type 'complete_inputs' in the QNial interpreter. <Error> messages are primarily in the 
    file 'Main.ndf' which hosts the 'complete_inputs' operation
											%  ; 
    Type & check results in file 'complete_inputs verification.txt' of:
    a. ' Milankovic_rows  Milankovic_cols ' then ' Milankovic ' 
    b. ' Solanki_rows  Solanki_cols '  (but NOT Solanki - there are no transformations) 
    c. ' datedebut  datefin  date_conversion ' 
    d. ' Milankovic_delta_t Solanki_delta_t civilisation_period ' 
    e. '  n_intrpsteps  n_poly ' 
    e. ' intrp_tdata  '   BUT don't type ' intrp_tseries   ' yet, this is long!!!
#
3.  Check  interpolations -     Verify the Interpolation routine on toy problems.
    Make sure that steps 1 and 2 have been completed, or re-load and run
    complete_inputs  
    a. Simply load the interpolations file ('make f2')  Test using the example 
       in the file 'Check  interpolations.ndf'.  
    b. ' make "all ', command ' complete_inputs ', and 
       command ' setdeftrace "interpolation_for_interval ' and
       ' interpolation_for_interval -3000 '
      -> compare to ' Check interpolate_for_interval.ndf '
      Note that the interpolation errors are too high!!
    

#
4.  Eventually, convert all of the above to a special header and verification file system

#  Current problems:
1.  Not robust with multiple makes without 'clearws' -  initialization not properly set up

#Copy the following to a separate QNial file window, so that you can rapidly get to an 
advanced point in the verification process.
make "all 
civic

#****************************
   Lessons learned

#  All global variable definitions should be declared "NONLOCAL" in each operation that 
   uses them (including 'EXTERNAL' declarations

#  arctan provides wrong answers for some problems, but the sine & cosine, if available, 
   can be used to select the right angle that yields the right tan