home *** CD-ROM | disk | FTP | other *** search
/ io Programmo 72 / IOPROG_72.ISO / soft / Codice / CRobots / Software / CRUTILS.ZIP / MANUALE.TXT < prev    next >
Encoding:
Text File  |  1999-08-30  |  13.7 KB  |  299 lines
  1. CRUtils - CROBOTS (TM) Ms-DOS & Linux Utilities ver.2.04
  2. Copyright (C) 1999 Maurizio Camangi
  3. Bug-report, E-Mail: <joshua@ascu.unian.it>
  4. Data ultimo rilascio : 30-aug-1999
  5.  
  6. Questo pacchetto (CRUTILS.ZIP) contiene i file :
  7.     BENCH.BAT,SGNIPS.EXE,BENCH.R
  8.         ALLTEST.BAT,BEST.BAT
  9.     CR
  10.     SOUND.EXE
  11.     CRUTILS.EXE
  12.     crutils
  13.     crutils.pp
  14.     COPYING
  15.     README.Linux
  16.  
  17. Legalese
  18. --------
  19.  
  20. CRUtils comes with ABSOLUTELY NO WARRANTY; for details read COPYING file.
  21. This is free software, and you are welcome to redistribute it
  22. under certain conditions; read COPYING file for details.
  23.  
  24. NOTA BENE:
  25. Tom Poindexter ha tutti i diritti d'autore sul programma CROBOTS.EXE (NON
  26. incluso nel pacchetto CRUTILS.ZIP).
  27.  
  28. 1- Il file di <enter> CR.
  29.  
  30.     Il file CR contiene soltanto il carattere CR (quello corrispondente
  31.     al tasto return). Indirizzandolo in input a CROBOTS.EXE si evita di
  32.     dover premere il tasto <return> ad ogni richiesta del programma
  33.     CROBOTS stesso. E` indispensabile nel caso di esecuzione multipla
  34.     del programma CROBOTS.EXE (ex : files batch, tornei ... )
  35.     poiche' e` praticamente impossibile premere ogni volta che ci
  36.     viene richiesto il tasto <enter>!.
  37.     Il modo per evitare questo spiacevole inconveniente e` eseguire
  38.     il programma ridirigendo il file di <enter>.
  39.     Ex : c:\crobots\crobots <cr -m100 -l200000 robot1.r robot2.r >result.log
  40.                 ^^^
  41.  
  42. 2- Il programma BENCH.BAT e SGNIPS.EXE.
  43.     
  44.     La procedura batch BENCH.BAT serve per valutare in modo approssimato
  45.     la velocita` del vostro PC in termini di SGNips (da non confondere
  46.     con i Mips!! :) ). La procedura non fa altro che lanciare il programma
  47.     CROBOTS.EXE in modo da eseguire 100,200 o 500 match tra 4 crobots BENCH.R
  48.     con il limite di 200000 cicli per match. Prima e dopo l'esecuzione di
  49.     CROBOTS.EXE si creano due files .LOG che recano come attributi la data
  50.     e l'orario della loro creazione. Il programma SGNIPS.EXE non fa
  51.     altro che calcolare il tempo impiegato ad eseguire il test prelevando
  52.     la data dai files .LOG e calcolare di conseguenza la velocita` del
  53.     PC.
  54.  
  55.     Essendo la velocita` di esecuzione e quindi la durata del test
  56.     dipendente dalla classe (nonche' dalla velocita` di clock) del
  57.     processore e` necessario specificare nella variabile d'ambiente
  58.     CPUID con il comando del DOS "SET", il tipo di CPU posseduta
  59.     (vedere documentazione inclusa nel file batch). SGNIPS.EXE
  60.     fornisce dunque la capacita` di calcolo del PC in termini di
  61.     SGNips ... che non sono altro che cicli/sec. della CPU virtuale
  62.     del programma CROBOTS (vedi la documentazione inclusa nel
  63.     pacchetto CROBOTS.ZIP originale).
  64.     Tale valore va tenuto a mente ed inserito ad ogni richiesta del
  65.     programma
  66.     CRUTILS.EXE. E` sufficiente eseguire il test BENCH.BAT una sola
  67.     volta a meno di una modifica software e/o hardware del PC che
  68.     influisca nelle prestazioni della CPU (ex: aggiunta/sostituzione
  69.     TSR, DRIVERS particolari ).
  70.  
  71.     BENCH.R e` un crobot che termina qualsiasi match in parita`, per
  72.     cui alla fine e` possibile sapere con certezza il numero di cicli
  73.     calcolati da CROBOTS.EXE. Gli SGNips calcolati sono in ogni caso
  74.     una STIMA, affetta da errore, per cui in caso di necessita` e`
  75.     possibile ripetere il test sostituendo il robot BENCH.R con un
  76.     altro che concluda egualmente i match SEMPRE in PARITA`!
  77.     NOTA: Il programma SGNIPS.EXE va utilizzato SOLO all'interno del file
  78.     batch BENCH.BAT.
  79.  
  80. 3- Il programma CRUTILS.EXE/crutils.
  81.  
  82.     Tale eseguibile contiene tre separate routine richiamabili al lancio
  83.     del programma, inserendo il numero associato all'utility desiderata.
  84.     L'eseguibile 'crutils' e` stato compilato con il pacchetto
  85.     FreePascal sotto Linux, ed e` quindi progettato per girare sotto
  86.     questo sistema operativo. Entrambe le versioni Ms-DOS e Linux sono
  87.     identiche tranne per alcune feature aggiuntive presenti nella
  88.     versione Linux, descritte nel documento README.Linux.
  89.  
  90.     Il file crutils.pp e` i file sorgente per le piattaforme Ms-DOS
  91.     (Turbo Pascal 6/7) e Linux (FreePascal).
  92.     Sebbene la versione binaria per Linux ('crutils', ottenuta
  93.     compilando il sorgente 'crutils.pp') sia piu` recente di quella
  94.     rilasciata per Ms-DOS (CRUTILS.EXE) e` possibile ricompilare il
  95.     sorgente con il Borland/Turbo Pascal 6.0 o 7.0 e riallineare la
  96.     versione Ms-DOS con quella Linux.
  97.  
  98.    Utility n.1 : Crobots batch file Creator.
  99.  
  100.     Tale utility e` stata scritta per creare automaticamente files batch
  101.     con i parametri da passare di volta in volta a CROBOTS.EXE, in modo
  102.     da poter creare tornei, test, senza problemi.
  103.  
  104.     Una volta scelta l'utility viene richiesto il numero di SGNips
  105.     calcolati dal PC posseduto. Tale valore e` reperibile eseguendo il
  106.     test BENCH.BAT, e serve ad effettuare una STIMA sul tempo di esecuzione
  107.     del file batch generato.
  108.  
  109.     Viene poi chiesto il numero di crobots da utilizzare per creare il file
  110.     batch finale. Questi crobots verranno passati come parametri al programma
  111.     CROBOTS.EXE in modo da coprire tutte le permutazioni possibili
  112.     (metodo del "girone all'italiana").
  113.  
  114.     NOTA: Nessuna modifica viene eseguita sull'ordine in cui vengono
  115.         passati come parametri i vari crobots al programma CROBOTS.
  116.         Pertanto i match sono ordinati in modo NON casuale a meno
  117.         di non utilizzare l'opzione relativa alla generazione di
  118.         un "torneo standard" descritta di seguito presente nel
  119.         solo eseguibile per Linux.
  120.  
  121.     Viene poi richiesto il numero di crobots da far combattere
  122.     contemporaneamente in ogni singolo incontro (da 2 a 4).
  123.  
  124.     Viene poi richiesto il numero di iterazioni da effettuare per
  125.     ogni singolo incontro tra 2,3 o 4 robots.
  126.     Il mumero di default e` 100, e viene usato nel caso in cui alla richiesta
  127.     si prema <enter> o si inserisca un valore non valido.
  128.  
  129.     Viene poi richiesto il numero di cicli massimo per ogni singolo match.
  130.     Anche qui il valore di default e` 200000, e viene usato nel caso in cui
  131.     alla richiesta si prema <enter> o si inserisca un valore non valido.
  132.  
  133.     NEW : Se si vuole generare un file di batch per un torneo standard e`
  134.     sufficiente rispondere "S" alla domanda che verra` posta dopo l'inserimento
  135.     del numero di partecipanti. Per default verranno utilizzati i valori
  136.     di 200000 cicli per incontro, 4 crobots in simultanea per incontro e
  137.     verra` automaticamente calcolato il numero di iterazioni da effettuare
  138.     (se il numero di crobots lo consente) affinche' ciascun crobots incontri
  139.     un altro crobots ALMENO in 1000 incontri.
  140.  
  141.     N.B. solo per la versione Linux: Il numero massimo di robots
  142.     partecipanti e` posto a 24. Gli incontri verranno generati in
  143.     ordine pseudo-casuale per ottenere una certa uniformita` di
  144.     risultati nello svolgimento del torneo stesso.
  145.  
  146.     Si chiede poi se i risultati di ogni incontro debbano essere salvati
  147.     sul file di report di default "log\crobots.log" o su di un file a piacere.
  148.  
  149.     A questo punto e` possibile inserire i nomi dei crobots sia in modo
  150.     manuale (uno alla volta), sia in modo automatico (ricerca dei files .R
  151.     nella directory specificata).
  152.  
  153.     Nel caso in cui i crobots vengano inseriti in modo Automatico
  154.     (di default, e` sufficiente premere "a", <enter> o una qualsiasi lettera
  155.     diversa da "m") viene chiesto di specificare il path dove cercare i robots.
  156.  
  157.     IMPORTANTE: Se la directory e` diversa da quella di CROBOTS.EXE
  158.     bisogna terminare il path con '\' altrimenti i crobots non verranno trovati !
  159.     (ex : se il path e` c:\crobots\src bisogna specificare c:\crobots\src\
  160.     o \crobots\src\ se il drive corrente e` c: ), altrimenti e` sufficiente
  161.     premere <enter>.
  162.     Tale path puo` essere o non essere passato come parametro insieme ai crobots
  163.     all'eseguibile CROBOTS.EXE.
  164.  
  165.     Nel caso in cui i crobots vengano inseriti in modo Manuale e` necessario
  166.     ricordarsi di inserire il path se i crobots non risiedono nella stessa
  167.     directory di CROBOTS.EXE.
  168.  
  169.     IMPORTANTE: Da questa versione in poi i nomi dei crobots devono essere
  170.     inseriti in modo "LOWERCASE" ! Questa scelta e` stata fatta per avere la
  171.     compatibilita` con i nome file utilizzati dai sistemi UNIX (ex: Linux).
  172.  
  173.     A questo punto il programma calcola tutte le combinazioni possibili
  174.     ( num_robots!/(num_match!*(num_crobots - num_match)!) ) e quindi tutti i
  175.     match da disputare (numeroincontri*numeromatchperincontro).
  176.  
  177.     Viene fornita anche una STIMA sul tempo di esecuzione degli incontri.
  178.     Questo valore viene calcolato in base al numero di incontri e match da
  179.     disputare, in base ad una stima statistica sui cicli da calcolare e in
  180.     base agli SGNips calcolati dal PC stesso.
  181.  
  182.     ATTENZIONE: Ne' il tempo di esecuzione dei vari incontri tra crobots reali
  183.     ne' i cicli impiegati, sono calcolabili in modo deterministico per cui
  184.     tale stima e` valida per orientarsi sull'ordine di grandezza del tempo
  185.     di esecuzione del file batch generato.
  186.  
  187.     NOTA: Se lo si ritiene necessario e` possibile modificare il test BENCH.R
  188.     per ottenere il valore degli SGNips piu` vicino alla realta`.
  189.  
  190.     E` possibile a questo punto salvare sul file 'start' tutti i
  191.     comandi del tipo
  192.     crobots -m match -l cicli robot1 ... <cr >>file_report
  193.     vederli su video o uscire.
  194.  
  195.     NOTA: Per utilizzare il file 'start', generato con la versione per
  196.     Linux, sotto Ms-DOS, rinominare il file in 'START.BAT' e seguire
  197.     le indicazioni elencate nella nota in appendice a questo
  198.     documento.
  199.  
  200.    Utility n.2 : Crobots LOG file Parser.
  201.  
  202.     Questa utiltiy serve per calcolare i punti accumulati dai crobots
  203.     nei vari scontri disputati e stilare una classifica finale, comprensiva
  204.     di tutti i dati statistici, nonche' di poter salvare questi dati su
  205.     file di testo compatibile con il formato testo CSV di Microsoft Excel e
  206.     ora anche in formato testo HTML (Netscape, Internet Explorer ... etc.).
  207.  
  208.     All'inizio e` necessario inserire i nomi dei crobots in modo manuale o
  209.     automatico, con le stesse modalita` dell'utility (vedere la modalita`
  210.     di inserimento del path di ricerca nella nota relativa all'utility n.1).
  211.  
  212.     Il programma non accetta nomi di crobots identici anche se trovati in
  213.     path differenti.
  214.  
  215.     E` poi necessario inserire il nome e l'ubicazione del file di report
  216.     che deve avere obbligatoriamente estensione .LOG. Tale report
  217.     e` ottenibile ridiregendo come output su file con il simbolo ">":
  218.     ex: c:\crobots\crobots ... [vari parametri] ... >report.log
  219.                             ^^^^^^^^^^^
  220.     o per incontri multipli il simbolo ">>".
  221.  
  222.     ATTENZIONE: Da questa versione in poi, per compatibilita` verso i sistemi
  223.     UNIX, affinche' il programma funzioni correttamente
  224.     e` necessario che i nomi dei crobots siano stati precedentemente
  225.     passati come parametri al programma CROBOTS in modo "LOWERCASE"
  226.     estensione ".r" inclusa (perche' tali devono apparire nel file di report!):
  227.     ex: crobots ... robot1.r robot2.r ... <-- Va bene.
  228.     ex: crobots ... ROBOT1.R ROBOT2.R ... <-- NO!
  229.             ^^^^^^^^ ^^^^^^^^
  230.     ex: crobots ... Robot1.r Robot2.r ... <-- NO!
  231.             ^     ^
  232.     NOTA: Se il file batch che contiene i comandi per l'esecuzione dei vari
  233.     incontri e` stato creato con l'utility n.1 tale regola
  234.     e` automaticamente rispettata!
  235.  
  236.     Viene poi fornita la classifica relativa ai crobots inseriti e al
  237.     file di report utilizzato, con la possibilita` di salvarla su file
  238.     di testo non formattato con nome e path del file di report ed
  239.     estensione .TXT. E` poi possibile salvare la classifica in un file
  240.     di testo CSV compatibile Microsoft Excel e un altro file in formato HTML;
  241.     in entrambi i casi il programma richiede path e nome del file da salvare.
  242.  
  243.    Utility n.3 : Cycles Counter.
  244.  
  245.     Tale mini-utility legge i files di report di CROBOTS e calcola
  246.     il numero totale di match disputati e la media cicli tenuta per
  247.     ogni singolo match. Viene poi riportata la media cicli del singolo
  248.     file e di tutti i files elaborati fino a quel momento.
  249.  
  250. 4- I files batch ALLTEST.BAT e BEST.BAT
  251.  
  252.         Questi files batch dai nomi alquanto espliciti sono un semplice
  253.     esempio dell'utilizzo dell'utility n.1 del programma CRUTILS.EXE,
  254.         e permettono di testare in modo abbastanza esauriente l'efficienza del
  255.         proprio crobot. E` sufficiente eseguire al prompt dei comandi
  256.         ALLTEST (oppure BEST) nomerobot (senza estensione).
  257.  
  258.     IMPORTANTE: Affinche' dopo il test sia possibile fare il parsing dei
  259.     files LOG con il programma CRUTILS.EXE e` necessario passare come parametri
  260.     ai file batch ALLTEST e BENCH i nomi dei crobots in modo "LOWERCASE".
  261.     
  262.     Il crobot da testare e i vari crobots avversari sono distribuiti
  263.     in directory differenti che ognuno puo` modificare a piacimento.
  264.         I dati finali vengono salvati su files .log che possono
  265.         essere in seguito analizzati con l'utility n.2 del programma CRUTILS.EXE.
  266.  
  267. 5- Il programma SOUND.EXE
  268.  
  269.     Tale "stupido" programma fa squillare l'altoparlante del PC
  270.     finche' non viene premuto un tasto. Utile da mettere come
  271.         ultimo comando da eseguire nei files batch generati da CRUTILS.EXE
  272.     in modo da poter essere avvertiti al termine di tutti i match.
  273.  
  274. 6- Appendice: compatibilita` UNIX/Linux
  275.  
  276.     Se volete utilizzare CRUTILS.EXE con i file di log generati dagli
  277.     scripts Linux e` necessario convertire i caratteri di fine riga LF
  278.     in CR+LF con programmi del tipo 'todos <infile >outfile'.
  279.  
  280. NOTA BENE: Tutti gli eseguibili .EXE sono stati compilati in Real Mode 80286
  281.         e NON possono essere eseguiti su PC di classe XT.
  282.         Non sono per niente protetti :( per cui, o inserite i dati
  283.         giusti o creapano miseramente! Tutto cio` per merito della
  284.         mia proverbiale pigrizia ;->.
  285.  
  286.         I file batch creati con CRUTILS.EXE possono essere convertiti
  287.         in script UNIX cambiando la "\" con la "/" e "%1.r" in "$1" o
  288.         "$1.r" e *viceversa*.
  289.         Fate attenzione, sotto UNIX, alla distinzione
  290.         tra lettere maiuscole e minuscole nell'uso di file e
  291.         programmi, non necessaria sotto    MS-DOS; e` semplicemente
  292.         possibile, sotto S.O. Linux, utilizzare il file binario
  293.         (linkato staticamente) ELF-i386 'crutils'.
  294.  
  295.                 Maurizio "Joshua" Camangi :^)
  296.                 joshua@ascu.unian.it
  297.  
  298. SGNIPS SPARAPAUS
  299.