use Makefile for all tasks

[merlinran]

It is based off #12 and the change specific to this PR is in a single commit 541629a

[sequoia-hope]

Make has always seemed pretty hard to follow for me. Are there any alternatives you can think of?

Is it just executing some commands? I am curious if we could achieve much the same results with a python script?

could call it acorn-run.py and mark the execute bit, so instead of calling
make simulation
we could call
acorn-run.py simulation

we could alias it to the command "arun" so we just type:

arun simulatiuon

Or is make really needed? Let me know your thoughts. Thank you!

[merlinran]

Some sort of build automation seems useful to, for example, rebuild the docker image automatically before running simulation if any of the requirements.txt gets changed, or some other guy updating to the latest code would find it fail to run because of missing Python packages, and spend some minutes to figure out why and do the docker build by themselves. We could do the check of timestamp and rebuilding in Unix shell, but that's less structural than a tool dedicated to this, and IMHO shell is messier and harder to debug than Makefile (the errors you encountered when running make in the other PR are due to differences among shell flavours). If we use Python, there would be tons of os.system/subprocess.popen to run the commands and get the output, which seems even more suboptimal.

I chose make because of its ubiquity - and many developers are more or less familiar with it. An alternative would be https://www.scons.org which is Python-like, but that is yet another domain specific language for most of the people to learn. Same for https://github.com/bazelbuild/bazel and others.

From my experience, Makefile seldom changes once gets established, and though the syntax has many dark corners I myself would frustrate too, the basic rules are simple. Actually the majority of the Makefile are plain shell scripts. I'll comment on the Makefile features. Lmk if they make sense to you and if not, we can discuss on the alternatives.

[merlinran]

I think this is basically it. I never dedicated time to learn make, just followed the Makefiles I had to make changes and checked the manual for things I didn't quite understand.

[merlinran]

Variables are similar to shell variables, you just need to reference them via $(var), instead of $${var}(${var} in normal shell, but since we are running shell scripts within Makefile, we need to escape $, similar to why we have to use \\ to represent \ in C string).

[merlinran]

. PHONY is to tell Make that the target is not a real file. Without it, if there's a file called list in the directory, make would think: the file is already there and up-to-date, I won't do anything.

[merlinran]

Since this is the first target in the file, make without a target simply runs this rule. And this rule has no dependencies.

[merlinran]

@ tells make to not prompt the command follows. The rest are just normal shell scripts. This rule is a trick to list the main targets from the Makefile itself.

[merlinran]

One caveat is to always use tab instead of whitespaces in the rule body, or make won't recognize it. Editor may warn you or correct for you if that happens.

[merlinran]

Here docker-image is a dependency of simulation. Before running the body of the rule, make first makes sure docker-image is up-to-date, by recursively checking the rule at L59 and running the body if needed.
In this case, the dependency chain is simulation <- docker-image <- Dockerfile <- vehicle/requirements.txt and server/requirements.txt. As long as the upstream target is newer than the downstream target, the rule body will be run. It would be very difficult to express such relationship in plain shell or Python.

[merlinran]

Here's again plain shell. Start the container if it doesn't exist, then docker exec it. test -z returns 0(success) if the output of the command is empty, in which case make docker-vehicle will run; Otherwise it returns 1(fail), and the && short-circuits. The command after ; is not affected, hence being run unconditionally.

[merlinran]

This is to allow me building and pushing the image for linux/amd64 while on my MacBook with M1 processor. Otherwise it just hits the next branch.

[merlinran]

This is supposed to be run inside the container, but since you are on Linux, you can also make test directly if all required Python packages are installed.