Proyecto 0 - CLI Command Line Interface

Objetivos

Para este proyecto se espera:

• Que el alumno construya el esqueleto sobre el cual se sustentarán las fases posteriores del compilador.
• Que el alumno obtenga una idea general sobre la organización y estructura del compilador.
• Un primer contacto con el manejo de repositorios de código con versiones.

Descripción

El CLI es el programa que interactúa con el usuario (Interfaz de línea de comandos). Este se encarga de llamar a los paquetes y clases indicadas para todo el proceso de compilar. Como ya fue visto, el compilador esta dividido en 2 grandes partes: Análisis y Síntesis, y cada una de estas partes se divide en varias partes (dependiendo del compilador) y esas son las partes de las que se encarga de llamar el CLI.

Para que ésta interfaz sea más amigable al usuario, el CLI debe ser capaz de presentar opciones, ayuda y resultados (si los hay) de la operación realizada. También hay que recordar que ninguna de las siguientes fases puede ejecutarse por sí sola, por lo que todo se debe ejecutar desde el CLI.

Tengan en cuenta que lo que ejecute el compilador para esta asignación no seguirá durante todo el proyecto, esto lo deben hacer para familiarizarse de nuevo con Java y estructurar mejor su proyecto. El CLI seguirá siendo el mismo pero cambiará la ejecución de cada fase en entregas posteriores.

1. Estructura de directorios:
   Deberán crear una serie de archivos en los que va a ir cada parte del compilador y por supuesto el archivo Compiler.java que controla al resto de archivos.

   Esta debe ser la estructura de directorios que deben usar, es importante notar que TODOS los directorios comienzan con minúsculas y los archivos .java comienzan con mayúsculas:

    /cc4
        /compiler
             Compiler.java
             Makefile
             /scanner
                 Scanner.java
             /parser
                 CC4Parser.java
             /ast
                 Ast.java
             /semantic
                 Semantic.java
             /irt
                 Irt.java
             /codegen
                 Codegen.java
             /opt
                 Algebraic.java
                 ConstantFolding.java
             /lib
                 Debug.java
                 ErrorHandler.java
                 antlr-4.0.0-complete.jar
             /test
                 scanner
                 parser
                 semantic
                 codegen
             /doc
   

Ejecución ———

Para ejecutar el compilador, se debe escribir un comando de esta forma:

java Compiler [option] <filename>

Su compilador debe soportar todas las opciones listadas a continuación. Cuando se ejecute su compilador y no se indique ninguna opción ni archivo de entrada, debe imprimir el mismo resultado de la opción -h.

-o <outname>		Escribir el output a un archivo de texto llamado <outname>.
	
	-target <stage>		Donde <stage> es uno de: scan, parse, ast, semantic, irt, codegen; la compilación debe proceder hasta la etapa indicada. 
				
				Por ejemplo, si <stage> es scan, una instancia de scan debe ser creada imprimiendo en el archivo de salida "stage: scanning". 
				
				Si es parse una instancia de parser debe ser creada a partir de la instancia de scanner imprimiendo "stage: parsing", 
				además del mensaje de scanner y así sucesivamente. 
	
	-opt <optimzation>	<optimization> es uno de: constant, algebraic; la compilación debe hacer solo la optimización que se le pida,
				y debe imprimir como en -target "optimizing: constant folding" o "optimizing: algebraic simplification". 
	
	-debug <stage>		Imprimir información de debugging. Debe haber un mensaje por cada etapa listada en <stage> de la forma "Debugging <stage>". 
				<stage> tiene las mismas opciones de -target, con la diferencia que se pueden "debuggear" varias etapas, 
				separandolas con ':' de la forma scan:parse:etc.
	
	-h			Muestra esta ayuda al usuario.

Adicionalmente:

Se debe proveer sólo un nombre de archivo, y no debe comenzar con -. las opciones deben de poder escribirse en cualquier orden y si hay opciones repetidas, únicamente se tomará en cuenta la última.

Funcionamiento ————–

Este es únicamente un esqueleto de lo que eventualmente sera su compilador, todos los archivos a excepción de Compiler.java deben pertenecer al sub-paquete correspondiente dentro del paquete compiler.

La clase principal Compiler.java debe llamar (dependiendo de los argumentos) a las demás clases, el orden de las clases comienza con Scanner y termina con Codegen, cada clase recibe en el constructor un objeto de la clase anterior, es decir, la clase Scanner recibe el nombre del archivo en el constructor (es la inicial), CC4Parser requiere de un objeto Scanner (lo recibe en el constructor), Ast recibe un objeto CC4Parser, y así sucesivamente.

Al instanciar a cada clase de las anteriores se debe imprimir al archivo el mensaje: stage: [stage] y si el debugging está activo, debe imprimir a pantalla: debugging [stage].

Las clases de la carpeta opt y de la carpeta lib no dependen de ninguna otra clase en su constructor y cada una de ellas tiene un uso concreto:

• Algebraic.java, se instancia cuando se usa la bandera opt.

• ConstantFolding.java, se instancia cuando se usa la bandera opt.

• ErrorHandler.java, esta clase maneja todos los errores, recuerde usar System.err para imprimir.

• Debug.java, maneja el debugging de todas las fases.

En la carpeta doc debe colocar su documentación y en la carpeta test los casos de prueba.

Control de versiones ——————–

Este es un proyecto largo y complejo, por lo que es una buena práctica utilizar sistemas de control de versiones, de forma que nos simplifique la vida el trabajo colaborativo sostenido por largos peridoso de tiempo. Por esto, es un requerimiento obligatorio del proyecto utilizar GIT para llevar el control del mismo.

Adicionalmente utilizaremos github como repositorio remoto, por lo que debe crear una cuenta, no se preocupe, es gratis! Para todo lo anterior necesita descargar e instalar git.

Le recomendamos leer y completar este tutorial, además puede consultar el libro on-line.

Para inicializar un repositorio git para su proyecto, debe seguir los siguientes pasos:

$ git init
  $ git remote add origin git@github.com:username/compiler.git
  $ git add .
  $ git commit -m "Commit inicial"
  $ git push -u origin master

Recuerde que debe reemplazar username, por su nombre de usuario en github.

¿Qué debe entregar?

Debe enviar los fuentes de su proyecto y la documentación del mismo. Su documentación debe incluir las siguientes partes:

• Una lista de clarificaciones, suposiciones, o adiciones al problema asignado. Las especificaciones del proyecto son bastante amplias: dejan muchas decisiones al implementador (ustedes), lo cual es un aspecto real de ingeniería de software y es mejor que empiecen a acostumbrarse. Si necesitan alguna clarificación, consulten a un auxiliar.

• Un resumen de su diseño.

• Una desecripción de su diseño top-level, análisis de alternativas de diseño que consideraron, y decisciones claves de diseño. Asegurense de documentar y justificar cualquier decisión de diseño que tomen. Cualquier decisión acompañada de un argumento convincente va a ser aceptada. Si se dan cuenta que hay errores o deficiencias en su diseño muy tarde en el proceso de implementación discutan estos errores y expliquen qué habrían hecho de manera diferente para evitar el problema.

• Una descripción de su diseño para módulos no triviales.

• Cualquier cambio que hayan tenido que realizar en etapas anteriores y por qué fueron necesarios estos cambios.

• Una breve descripción de temas de implementación interesantes. Esto debe incluir cualquier algoritmo, técnica, y estructura de datos no trivial.

• Una lista de problemas conocidos de su compilador, y tanta información como le sea posible acerca de la causa de estos problemas. Si su proyecto falla alguno de los casos de prueba, y no pueden arreglar el problema, describan lo que entienden acerca del problema. Si descubren problemas que no pueden arreglar en su proyecto usando sus propias pruebas y estos problemas no son atrapados por los casos de prueba provistos, describan el problema tan específicamente como les sea posible. Si esto causa que su proyecto falle los casos de prueba escondidos, puede que todavía reciban puntos por considerar el problema. Si el problema no es revelado por los casos de prueba escondidos, no se les penalizará.

Entrega

La entrega se realizará a través del GES antes de las 23:55:00 del día Lunes 21 de Julio de 2014, debe enviar un archivo llamado grupo.zip conteniendo todas sus clases y demás archivos indicados previamente.

Al desempaquetar su entrega, debemos poder ejecutar su proyecto de la siguiente forma:

java Compiler [option] <filename>

Si no se cumple lo anterior, se verán en riesgo de recibir una penalización del 50%, por lo que tenga mucho cuidado con esto.