/*
 * $Id: compiler.txt,v 1.2 2001/07/30 13:39:30 ckedem Exp $
 */

/*
 * Las siguientes partes son derechos adquiridos de sus autores individuales.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Alejandro de Gárate <alex_degarate@hotmail.com>
 * Documentación en Español de:  Opciones del Compilador
 *
 * Vea doc/license.txt por los términos de la licencia.
 *
 */


/*  $DOC$
 *  $FUNCNAME$
 *      Opciones del Compilador
 *  $CATEGORY$
 *      Documentación
 *  $ONELINER$
 *      Opciones del Compilador
 *  $DESCRIPTION$
 *
 *      Invocando al compilador Harbour:   </par>
 *      ===============================   </par>
 *
 *         harbour <archivo[.prg]> [opciones]   </par>
 *      or                                      </par>
 *         harbour [opciones] <archivo[.prg]>    </par>
 *      or   </par>
 *         harbour [opciones] <archivo[.prg]> [opciones]   </par>
 *
 *
 *      Las opciones de la línea de comandos debe ser separada, al menos por
 *      un espacio en blanco.   </par>
 *      Las opciones pueden comenzar con el carácter '/' ó '-',    </par>
 *
 *      Opciones de la línea de comandos de:   </par>
 *      ====================================   </par>
 *
 *      /a               Declaración Automática de memvar    </par>
 *      -----------------   </par>
 *          Esto causa que todas las variables declaradas por las sentencias
 *          PARAMETER, PRIVATE ó PUBLIC sean automáticamente declaradas como
 *          variables MEMVAR.          </par>
 *
 *      /b               Información de depuración (Bug)  </par>
 *      -----------------   </par>
 *          El compilador genera toda la información requerida para depuración </par>
 *
 *      /d<id>[=<val>]   #define <id>   </par>
 *      -----------------   </par>
 *
 *      /es[<nivel>]     establece la Severidad de la salida (Exit Severity) </par>
 *      -----------------   </par>
 *
 *          /es or /es0 - Todas las advertencias son ignoradas y el código de
 *                        salida retornado por el compilador (accedido por el
 *                        comando de DOS ERRORLEVEL) es igual a cero si no
 *                        hay errores en el archivo fuente compilado. </par>
 *          /es1        - Cualquier advertencia genera un código de salida
 *                        distinto de cero, pero la salida es aún creada. </par>
 *          /es2        - Cualquier advertencia es tratada como error y ningún
 *                        archivo de salida es creado. El código de salida es
 *                        establecido a un valor distinto de cero.  </par>
 *
 *      /g<tipo>         Generación del tipo de archivo de salida <type> </par>
 *      -----------------                                  </par>
 *
 *          /gc          tipo de salida: fuente de lenguaje C (.c) (defecto) </par>
 *          /gf          tipo de salida: Windows/DOS OBJ32 (.obj)      </par>
 *          /gh          tipo de salida: Objeto Portable de Harbour (.hrb) </par>
 *          /gj          tipo de salida: fuente de Java (.java)         </par>
 *          /gp          tipo de salida: fuente de Pascal (.pas)        </par>
 *          /gr          tipo de salida: recursos de Windows (.rc)      </par>
 *
 *      /i<ruta>         agrega la ruta de búsqueda de archivos #Include  </par>
 *      -----------------   </par>
 *
 *      /l               suprime la información del número de Línea   </par>
 *      -----------------   </par>
 *          El compilador no genera el número de línea del código fuente
 *          en el archivo de salida. La función PROCLINE() retornará cero
 *          para los módulos compilados usando esta opción.   </par>
 *
 *      /m               compilar el Módulo actual solamente  </par>
 *      -----------------   </par>
 *
 *      /n               sin procedimiento de inicio implícito </par>
 *      -----------------   </par>
 *          El compilador no crea un procedimiento con el mismo nombre
 *          que el del archivo compilado.  Esto significa que algunas
 *          declaraciones puestas antes de la primera sentencia de
 *          PROCEDURE ó FUNCTION tienen el alcance del archivo y pueden ser
 *          accedidas/usadas en todas las funciones/procedimientos definidos
 *          en el archivo fuente compilado. Todas las sentencias ejecutables
 *          puestas al principio del archivo y antes de la primera sentencia
 *          de PROCEDURE ó FUNCTION son ignoradas.  </par>
 *
 *      /o<ruta>         unidad de disco y/o ruta para el archivo de salida </par>
 *      -----------------   </par>
 *
 *      /p               genera un archivo de salida Pre-procesada (.ppo) </par>
 *      -----------------   </par>
 *          El compilador solamente crea el archivo que contiene el
 *          resultado del archivo fuente pre-procesado.   </par>
 *
 *      /q               Quieto  </par>
 *      -----------------   </par>
 *          El compilador no imprime ningún mensaje durante la compilación
 *          (excepto la información del copyright).   </par>
 *
 *          /q0          que permanezca realmente Quieto y no muestre ni
 *                       siquiera la información del copyright.   </par>
 *
 *      /r[<libreria>]   solicita al linker Revisar por <libreria> (ó ninguna) </par>
 *      -----------------   </par>
 *          Actualmente no soportado en Harbour.           </par>
 *
 *      /s               solo chequeo de Sintaxis.          </par>
 *      -----------------   </par>
 *          El compilador chequea la sintaxis solamente. Ningún archivo de
 *          salida es generado.  </par>
 *
 *      /t<ruta>         ruta para la creación de un archivo Temporario  </par>
 *      -----------------   </par>
 *          Actualmente no usado en harbour (El compilador de harbour no
 *          crea ningún archivo temporal)   </par>
 *
 *      /u[<archivo>]       Usar la definición de comando establecido en el
 *                          <archivo> (ó ninguno)   </par>
 *      -----------------   </par>
 *          Aún no soportado.   </par>
 *
 *      /v               las Variables son asumidas como M->   </par>
 *      -----------------   </par>
 *          Todas las variables sin declarar ó unaliased son asumidas como
 *          variables MEMVAR (variables privadas ó públicas). si este switch
 *          no es usado entones el alcance de estas variables es chequeado
 *          en tiempo de ejecución.    </par>
 *
 *      /w[<nivel>]      Establece el número de nivel de las advertencias
 *                       (Warnings) (0..4, por defecto es 1)   </par>
 *      -----------------   </par>
 *
 *         /w0         - sin advertencias                          </par>
 *         /w or /w1   - advertencias compatibles con Clipper      </par>
 *         /w2         - algunas advertencias útiles ausentes en Clipper </par>
 *         /w3         - advertencias generadas para extensiones al lenguaje
 *                       hechas en Harbour. También habilita el chequeo de
 *                       sintaxis fuertemente tipeada pero sólo advierte
 *                       contra los tipos declarados, o los tipos que pueden
 *                       ser calculados en tiempo de compilación.    </par>
 *         /w4         - habilita advertencias acerca de operaciones que son
 *                       sospechosas, lo cual significa que si se mezclan tipos
 *                       sin declarar ó tipos que no pueden ser calculados
 *                       en tiempo de compilación, junto con los tipos ya
 *                       declarados, una advertencia será generada.   </par>
 *
 *      /x[<prefijo>]    establece el símbolo del prefijo agregado al nombre
 *                       de función (para archivo.c solamente)   </par>
 *      -----------------   </par>
 *          Establece el símbolo del prefijo agregado al nombre de función
 *          de inicio (en la salida de lenguaje C, actualmente). Esta función
 *          es generada automáticamente para cada módulo de PRG compilado.
 *          Este prefijo adicional puede ser usado para suprimir problemas
 *          con símbolos duplicados durante el enlazado de una aplicación
 *          (linking) con alguna librería de terceros.   </par>
 *
 *      /y               seguimiento de la actividad de Lex & Yacc   </par>
 *      -----------------   </par>
 *          El compilador Harbour usa las utilidades FLEX y YACC para analizar
 *          el código fuente y generar el archivo de salida requerido.
 *          Esta opción sigue la actividad de esas utilidades. </par>
 *
 *      /z               suprime el cortocircuito lógico (.and. y .or.) </par>
 *      -----------------   </par>
 *
 *      /10              restringe la longitud de símbolos a 10 caracteres. </par>
 *      -----------------   </par>
 *          Todos los nombres de variables y de funciones son cortados a un
 *          máximo de 10 caracteres.  </par>
 *
 *
 *      Compilación en modo lote (batch).   </par>
 *      ================================   </par>
 *
 *       @<archivo>         compila la lista de módulos en el <archivo>   </par>
 *      -----------------        </par>
 *          No soportado aún.    </par>
 *
 *
 *
 *      Conocidas incompatibilidades entre compiladores harbour y clipper  </par>
 *      =================================================================   </par>
 *
 *      NOTE:   </par>
 *        Si desea librerías de compilación y ejecución 100 % compatibles,
 *      entonces Ud. debe definir: HARBOUR_STRICT_CLIPPER_COMPATIBILITY.
 *      Esta opción debe ser definida en el archvivo ../include/hbsetup.h
 *      (en efecto esta opción es puesta en un comentario por defecto - Ud.
 *      necesita remover los caracteres /* */ solamente. Este cambio debe ser
 *      realizado antes de invocar la utilidad make.   </par>
 *
 *
 *      Manejo de variables sin declarar </par>
 *      --------------------------------   </par>
 *        Cuando un valor es asignado a una variable no declarada y la opción
 *      -v  de la línea de comandos no es usada, entonces el compilador
 *      Clipper asume que la variable es una variable PRIVATE ó PUBLIC y
 *      genera un opcode POPM (pop memvar).   </par>
 *
 *      Cuando el valor de una variable no declarada es accedido y la opción
 *      -v de la línea de comandos no es usada, el compilador Harbour genera
 *      un opcode  PUSHV (push variable) para determinar el tipo de variable
 *      en tiempo de ejecución

 *      Si un campo con el nombre requerido existe en el area de trabajo
 *      actual, entonces este valor es usado. Si no existe el campo, entones
 *      una variable PRIVATE ó PUBLIC es usada (si existe).   </par>
 *
 *        El compilador Harbour genera un opcode para determinar el tipo de
 *      variable en tiempo de ejecución (POPVARIABLE or PUSHVARIABLE) en
 *      ambos casos (asignación y acceso).   </par>
 *
 *      La diferencia puede ser chequeada por el siguiente código:   </par>

 *          <fixed>
 *      PROCEDURE MAIN()
 *      PRIVATE myname
 *
 *        DBCREATE( "TEST", { { "MYNAME", "C", 10, 0} } )
 *        USE test NEW
 *        SELECT test
 *        APPEND BLANK
 *
 *        FIELD->myname  := "FIELD"
 *        MEMVAR->myname := "MEMVAR"
 *
 *        myname := myname + " assigned"
 *
 *        // In Clipper: "FIELD",  In Harbour: "FIELD assigned"
 *        ? FIELD->myname
 *
 *        // In Clipper: "MEMVAR assigned", In Harbour: "MEMVAR"
 *        ? MEMVAR->myname
 *
 *        USE
 *
 *      RETURN
 *     </fixed>
 *
 *      Pasando por refeerencia una variable no declarada   </par>
 *      -------------------------------------------------   </par>
 *        El compilador Harbour usa un opcode especial PUSHP para pasar una
 *      referencia  a una variable no declarada ( el operador '@' ). El tipo
 *      de la variable pasada es chequeada en tiempo de ejecución (field or
 *      memvar). Sin embargo las variables de campo no pueden ser pasadas por
 *      referencia. Esto significa que Clipper chequea sólo la variable memvar
 *      y no mira por una de campo.
 *      Esta es la razón por la cual el compilador Harbour usa el opcode
 *      habitual PUSHMEMVARREF en estos casos. Nótese que el comportamiento
 *      en tiempo de ejecución es el mismo en Clipper y en Harbour - sólo los
 *      opcodes generados son diferentes.   </par>
 *
 *
 *      Manejo de mensajes a objetos   </par>
 *      ----------------------------   </par>
 *
 *        El seteo de HARBOUR_STRICT_CLIPPER_COMPATIBILITY determina
 *      la forma en que el envío encadenado de mensajes es manejado </par>
 *
 *      Por ejemplo, el siguiente código: </par>
 *
 *      a:b( COUNT() ):c += 1   </par>
 *
 *      será manejado como:   </par>
 *
 *      a:b( COUNT() ):c := a:b( COUNT() ):c + 1   </par>
 *      en modo de compatibilidad estricta y  </par>
 *
 *      temp := a:b( COUNT() ), temp:c += 1   </par>
 *      en modo no-estricto.   </par>
 *
 *        En la práctica, Clipper llamará a la función COUNT() dos veces:
 *      La primera vez antes de la adición y la segunda después de la
 *      adición.
 *      En Harbour, COUNT() será llamada sólo una vez, antes de la adición. </par>
 *
 *        El método Harbour (no-estricto) es:   </par>
 *      1) Más rápido   </par>
 *      2) Garantiza que la misma variable de instancia del mismo
 *         objeto será cambiada.  </par>
 *
 *      (Ver también: ../source/compiler/expropt.c)   </par>
 *
 *
 *      Inicialización variables estáticas     </par>
 *      ----------------------------------      </par>
 *
 *      Hay una diferencia en la inicialización de las variables estáticas
 *      que son inicializadas con un bloque de código que refiere a una
 *      variable local. Por ejemplo:   </par>

 *      <fixed>
 *      PROCEDURE TEST()
 *
 *      LOCAL MyLocalVar
 *      STATIC MyStaticVar := {|| MyLocalVar }
 *
 *        MyLocalVar :=0
 *        ? EVAL( MyStaticVar )
 *
 *      RETURN
 *      </fixed>

 *      El código de arriba compila bien en Clipper, pero éste genera un
 *      error de ejecución:
 *           Error/BASE 1132 Bound error: array access
 *      Called from (b)STATICS$(0)   </par>
 *
 *      En Harbour este código genera un error en tiempo de compilación:
 *      Error E0009 Illegal variable (b) initializer: 'MyLocalVar'   </par>
 *
 *      Ambos Clipper y Harbour estan manejando todas las variables locales
 *      usadas en una forma especial: ellas son separadas de la pila (stack)
 *      local de la función / procedimiento donde ellas son declaradas.
 *      Esto permite acceder a estas variables despues de la salida de una
 *      función / procedimiento. Sin embargo todas las variables estáticas
 *      son inicializadas en un procedimiento separado ('STATICS$' en Clipper
 *      y '(_INITSTATICS)' en Harbour) antes del procedimiento principal y
 *      antes de todos los procedimientos INIT. Las variables locales no
 *      existen en la pila de evaluación (eval stack) donde las variables
 *      estáticas son inicializadas, así ellas no pueden ser separadas.  </par>
 *
 *  $END$
 */
