Repositories

All project step repositories will be setup through Github Classroom.

• A link will be posted on BrightSpace for each step, through which you can setup your repository.
• If you are in ECE 468/573 and you have a partner, for step 1 and beyond, the setup link will let you choose your team with your partner and have you both working on the same assignment repository
  • Step 0 contains registration of your Purdue username and is thus a required individual assignment.
  • Teams need to be formed before step 1 deadline and you need to commit to the team composition for the remainder of the project.
• Experiences working with git and github would be recommended for this project.
  • Step 0 contains a brief introduction and links to more resources for these topics.
• To clone your repository, use the following format: git clone git@github.com:ECE468/repository-name-here. For example, to clone step 1 you would do git clone git@github.com:ECE468/fa2023-step1-NAME.git (replace NAME with your team name).
• Your repository will be initialized with:
  • the proper starter code
  • a Readme file which serves as the instruction and description of the step (These Readme files will be posted as instructions to each individual steps on this website, as well), and
  • Sample Makefile and runme scripts that would work out of the box
  • A helper testall script to run all public tests on the current code
    • Under correct environment, use ./testall from the repo root directory to invoke the script

You are free to change any of the starter code components, as far as your code works under the environment as described below, it would be accepted.

Grader interface and Language selection

In principle, our grader is language-agnostic, and is only expecting your project repository to expose the following interfaces:

Under the standard grading environment described in the next section:

• Your repository contains a proper Makefile such that:
  • make clean cleans up all intermediate files
  • make compiler prepares your compiler for running
    • Typically this means compilation of your own compiler, but for scripting languages like python, there might be not too much that needs to happen
• Your repository contains a proper runme script such that:
  • ./runme input_file output_file runs your compiler against input_file and writes the output of your compiler to output_file

The grader will use these interfaces to produce output files from your compiler and check the correctness and performance of the outputs.

However language-agnostic the grader can be, the starter code that most students will be basing their projects on still need to be in a certain language. Officially, our supported starter code is in Java, and by default all pre-shipped Makefile and runme scripts in starter code is using Java.

But this year, we are starting to provide experimental python starter code. For those who wish to use the python starter code, please follow the below instructions:

• Create a file named using-python in the root of your repository
  • The content of the file does not matter, it just needs to be a regular file (not a directory or link)
  • In a Unix environment this could be commonly done by running touch using-python from repository root
• Pre-shipped Makefile and runme scripts will be calling python version from this point
• Work on python/ directory from the starter code
  • src/ directory from the starter code contains the default Java version, and need not to be changed or used anymore since you selected python
• You need to do this for every single step for step 1 and beyond, since language selection only applies to the current step
  • step 0 does not have coding part, thus no need for selection
  • you can go back to Java version at any time, but probably need to re-do previous steps if later steps depend on the previous ones.

Environment

Code, scripts and programs may behave differently under different computing environment, to unify the outcome of our project grading, we have configured a standard environment, under which all project grading will be done.

You must make sure that your code works under this environment for the grader to grade you correctly, so it is highly recommended that you setup such an environment yourselves so that you could develop and test under the exact same environment.

Reference environment container

A reference environment would be provided as a Container though this repository. Pre-built container images are ready in Github Container Registry here.

This is the official reference environment, all grading will actually be done in this container.

To setup this reference container, you need a working container engine installation. The most common engines are docker and podman. Please refer to their official documentation if you need to install one.

• Under a working container engine installation, you now can pull the image from registry:

  docker pull ghcr.io/ece468/project-env
  

• And you can run a container with this image:

  docker run -it <other container flags> ghcr.io/ece468/project-env
  

• A very typical set of flags would be giving the container a name, also using volumes to map your project folder from the container host into the container:

  docker run -it --name compiler_project -v /path/to/project/repo/folder:/home/user/repo ghcr.io/ece468/project-env
  

• And with a name, after exiting the container, it could be later re-started with:

  docker start -ia compiler_project
  

• Note: for podman engine, replace all docker in commands above with podman

  • A side note: in the rare case that you are using rootless podman setup, to get file permissions correct across volumes, you may need to add --userns=keep-id to your podman startup command. More detailed readings here

• Note: in the case that we need to change the environment in the future, all repos and registries will be updated as well, and you need to re-pull and re-run the containers to get updated environments in such case

Simulated environment on ecegrid

For those who do not want or are not able to setup a working container engine installation, we also provided another simulated environment on ecegrid. To use this environment, do the following:

1. Login to any ecegrid machine (e.g. ecegrid-thin1.ecn.purdue.edu) either using SSH, or in a browser at https://ecegrid.ecn.purdue.edu.
2. Run the environment setup script (in a terminal) like so: source ~ee468/bin/setupenv
3. Navigate to your project directory; make should now work as expected.

NOTE: you must run the setup script for each new terminal/SSH connection, or else you will very probably get strange errors.

Disclaimer: ecegrid simulated environment is provided only for convenience, if any inconsistencies occur, please refer to the official container as the standard.

Environment details

For those with an adventurous heart wanting to setup the environment themselves, or those geeky enough to wonder what the environments really are and it disturbs their sleeps, here are some details about the environmental assumptions that our scripts and graders would make when running:

• bash and make are available in PATH.
• java and javac are available in PATH, and JDK version is Java 11.
• python3 is available in PATH, and points to a python 3.9.2 installation
• The above-mentioned python installation has the following packages:
  • (grader only, not necessary for development and testing) sh
  • (for python starter code users) antlr4-python3-runtime=4.9.1
• The path to the complete ANTLR 4.9.1 jar file is in CLASSPATH
• Either:
  • antlr script is available in PATH to invoke the ANTLR 4.9.1 Tool
  • ANTLR_TOOL environment variable is set to the correct command to call the ANTLR 4.9.1 Tool

Submission

You need to tag your submission using the git tag submission and push it to your Github repo to submit any step:

git tag submission
git push --tags origin

(assuming that origin refers to the github remote in your repo)

And to override your submission with a new one, you need to do that tagging and pushing with the force flags:

git tag -f submission
git push --tags -f origin

• Once you tag and push a submission, if the grader is already online for that step, the grader will be automatically run on it.
  • The status of the grader deployment will be announced through Piazza.
  • The grader would be automatically run on all latest submission tags that are already pushed when it gets deployed, to grade for all early submissions submitted before grader deployment
• Do not use this feature to repeatedly test your code, you will be rate-limited.
• Your overall grade will be determined based on your highest-scoring submission.
• The grader will give you feedback in a separate grade branch in the form of two files named grade.txt and output.txt.