In this post, I’ll cover getting set up to develop the Grue Z-Machine implementation. By the end of this post, the goal is to have the start of a working project.
Here, I, as an author, and you, as a reader, have an interesting situation to consider.
My goal is to create a Z-Machine implementation. Consider this an experiment that I’m conducting. I want someone else to be able to replicate my experiment, should they choose. At the very least, I want someone to be able to read about my experiment should they be interested. Your goal may be to craft your own experiment, perhaps using mine as the basis for yours. Or your goal may be to follow along exactly with my experiment, assuming you might learn something from my fumbling around.
I won’t be able to know if our individual goals align. What I do know is that when you propose an experiment, you should make it possible for others to replicate it. That means I need to make my experiment available. That also means I need to tell you how to get and set up the experiment.
Regarding blog relevance, testers must be able to get at and see the same artifacts that developers use as they develop their applications, particularly if those artifacts are oracles. See the previous post for more on that latter topic. Testers must be able to build and run a local copy of the code on their own machines. It’s dismaying how often I see this is not the case in my professional career.
Regarding career relevance, I recently did a team exercise with some testers where I provided a series of such experiments, essentially automation repositories. And literally, none of them even bothered to download and try the experiments as they were provided.
Getting Set Up: The Repo
The repo holding my code is available at Grue. A challenge here is that this is a repo that is going to be evolving over time as these posts are created. I’m carrying out this experiment in real time, as it were. What this means is that when someone reads this post, the repository may have moved along considerably in its development path. To mitigate this a bit, I will use a tagging scheme.
I like to see how any project I might want to use is set up. In the case of Grue, in the previous post I mentioned that I’m using Poetry as the project manager, and thus, I’m also using a pyproject.toml file.
If you’re into Python, you are likely somewhat familiar with PEP 621. If you’re not into Python, it won’t be very meaningful to you. The short story is that it’s a standard that the tools are being asked to follow. At the time I write this, Poetry does not fully comply with that standard. So, I’m using a development version of Poetry that does. See this pull request for more details on that.
Getting Set Up: What’s In Place?
In that pyproject configuration file, you can look under the sections “tool.poetry.group.dev.dependencies” and “tool.poetry.group.test.dependencies” which, as you might guess, show what things the Grue project depends on for development and testing. As a tester, those lists show me that a test runner is being used (pytest) along with an assertions or expectations library (expects). I also see a static type checker in place (mypy). What I don’t see in those lists are any formatters or linters. How much that matters to you depends on your level of experience. I like using a tool called pipx to install common Python applications. Here is a list of what I have in my pipx environment.
Specifically, the tools black (formatter) and ruff (linting) are available for use. I use them globally via pipx rather than as part of my dependencies. You’ll notice in my pipx list that I have poetry and poetryp. This is necessary because, as mentioned earlier, Poetry is transitioning to supporting the correct form of the pyproject.toml configuration. You can follow the directions in the previously mentioned pull request to get the development version. In doing those steps, I used the suffix “p” which is my development Poetry version is called poetryp.
When Poetry does support the full pyproject.toml standard, I will come back and edit these posts. That will make the process a lot simpler.
If I were looking at this code base myself, I would know the developer(s) are possibly taking internal qualities seriously given the tool chain I’m seeing. That presumes said developer(s) have an easy way to run all those tools and look at the results. Which I should likewise be able to do as a tester. Remember: this is an experiment. In the case of this project, I’m using invoke to make it easy to run everything I need. This is all handled via the tasks.py file. You’ll notice here that I’ve conditionalized the commands to run poetryp rather than just poetry. I was debating whether to bother with all this, but:
- I really like Poetry over options like Hatch or PDM.
- I believe in supporting the actual pyproject.toml standard; thus, I didn’t want to use “old (current) Poetry.”
- This indicates what you sometimes encounter in the wild as you learn how someone’s project is set up.
Given all this, you might ask: why even bother with Poetry or any such tool? Mainly because Python is heavily dependent on the idea of running things in a virtual environment, particularly when your project has dependencies. Tools like Poetry make that really easy to manage, because it creates the environment, installs the dependencies, as well as your own project, and makes it possible to run your project as a user will run it.
So if you want a set up just like mine:
- Follow the steps in the PR and name your development version of Poetry poetryp.
- Install black and ruff in pipx.
I set up Poetry to create my virtual environments in my project directory rather than somewhere else on my system. That’s not necessary. But if you do want to do that, I recommend changing Poetry’s virtualenvs.in-project configuration to true. You can read up on Poetry configuration. But, again, this is not required.
Getting Set Up: Can I Run It?
If you follow those steps, you can first clone the repository:
git clone https://github.com/jeffnyman/grue.git
I mentioned I’m going to use a tagging strategy so once you have the repository cloned, you can enter that directory and check the tags:
git tag
This will show all available tags. I have no idea what you will see since I have no idea when you might be reading this post. What I can say, however, is that tag 0.0.1 is the initial state of the application. So what that means is you could check out that tag to get where I was at when I wrote this post:
git checkout v0.0.1
This will be a pattern I try to apply in these posts as I go on. How well that will work in practice remains to be seen. Regardless of what tag you happen to be at, to get started you can do this from within the project directory:
poetryp install
That will set up the virtual environment and install the necessary dependencies. You can run the program by:
poetryp run grue
Not much will happen. At version 0.0.1, you’ll just get a banner text indicating that the app is installed. As one of my runtime dependencies, I’m using something called rich-click to generate a relatively nice command line experience.
poetryp run grue --help
That’s a bit of an affectation but since Grue is likely to be a command line application, I like knowing I have a relatively robust way to handle actions at the command line.
You can run the tests, minimal as they are at version 0.0.1, if you want:
poetryp run pytest
To run all those code quality tools I mentioned earlier, you can do this:
poetryp run invoke check
That causes all the tasks in the tasks.py module to execute. Obviously this requires the tools to be installed and available.
You’re Set Up!
You now have a working Grue implementation. Again, none of this is necessary if you are just reading along to learn more about the Z-Machine and how to implement one. But if you did want to start with your own project, my repo is probably not going to be a bad start to that. With all this context and set up out of the way, the next post in this series will begin discussing exactly how to implement a Z-Machine by first understanding what the Z-Machine fundamentally is.
