Skip to content

Add track installation instructions #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
codingthat wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add track installation instructions #97

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8fd6f0b
Add track installation instructions
codingthat Apr 30, 2025
07cdb3c
Inline refs and single-sentence-per-line
codingthat May 1, 2025
444cd35
Include test setup instructions
codingthat May 1, 2025
107e961
Add clarifications:
codingthat Jul 17, 2025
47b1f52
Merge branch 'exercism:main' into add-installation
codingthat Jul 17, 2025
c82456f
Fix exercism workspace location
codingthat Jul 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 50 additions & 9 deletions docs/INSTALLATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,56 @@
# Installation

<!-- TODO: write document
## Installing Godot Engine
Copy link
Member

@meatball133 meatball133 Apr 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The idea here is that these should be instructions to setup the language for local testing. If it is meant that users should be using docker for testing then these docs should describe how to setup that for different os.

Copy link
Contributor Author

@codingthat codingthat May 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure it's about testing, per se — there's both docs/TESTS.md and exercises/shared/.docs/tests.md for that, hence my WIP branch for those.

The spec and example for this docs/INSTALLATION.md seem to point more to just installing Godot itself, no?

Copy link
Member

@meatball133 meatball133 May 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is supposed to tell you how to install so you can test the tests locally.

I mean in most cases, say Python. You would install Python and then you could install the library needed and then simply run pytest and you would get the output. And some languages doesn't need any dependencies at all and have everything built in. So for Godot, if you need like a bash script for it to work. Then these instructions should tell you how to install that script for example.

Copy link
Contributor Author

@codingthat codingthat May 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, fair enough — but then what goes in TESTS.md for Godot? Should it just point back to INSTALLATION.md because there's nothing else to say like other tracks might (skipped tests, etc.)? Or duplicate its info (doesn't sound ideal, but then again, there's explicit mention of doing that for resources vs. help)?

Copy link
Member

@meatball133 meatball133 May 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the difference between installation and tests is that installation says what/how you install to tests. But tests say how you test. So for python would that be something like:

INSTALLATION.md:

  • How to install python
  • How to install libraries

TESTS.md:

How to test e.g:

Find the folder with the exercise then cd into that folder

cd path/exercise

Then you have to call pytest.

Copy link
Contributor Author

@codingthat codingthat May 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so, I will (once we agree on how the testing scripts should look, and finish them) move my WIP stuff so most of it is in this file. However, I'm not sure that's the correct move, because then there's not a real distinction between TESTS.md and the shared tests.md.

Here's what seemed to jive with the general track info docs as well as the comments in the templates:

  • INSTALLATION.md: about installing the tech itself (basically a link to the official docs plus a note about which version makes sense for Exercism) (note: nothing about tests)
  • TESTS.md: how to install local test runner infrastructure
  • shared tests.md: how to run local test runner infrastructure

And actually it's interesting you use Python as an example, because https://exercism.org/docs/tracks/python/installation is not at all about testing. Then its TESTS.md says e.g. how to install pytest. (Then I assume its shared tests.md it how to run tests for a single local exercise.)

However, it does seem that the "how to run a test" part is duplicated from the shared tests.md to the overall TESTS.md.

Either way, I think I did do the non-test installation instructions correctly in the end. OK to merge the current PR?

Copy link
Contributor Author

@codingthat codingthat Jul 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@meatball133 when you have a moment, let me know if this part is OK. Thanks!! :)


This document should describe what the student needs to install
to allow working on the track on their local system using the CLI.
The GDScript track is built on top of [Godot Engine][godot-engine], which runs on Windows, Linux, macOS, and Android.
Copy link
Member

@BNAndras BNAndras Jul 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This implies a student can solve exercises locally on those platforms, but we're later saying you need to run the test runner which apparently is Linux-only. So we should be clear upfront about this perhaps with an Exercism caution block so the student doesn't get frustrated after installing Godot locally.

Copy link
Contributor Author

@codingthat codingthat Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great point! @meatball133 mentioned the possibility of providing a PowerShell equivalent to the local test runner, but since it depends on run.sh from the test runner repo, we'd need a PS equivalent there as well. (Is it OK if I were to add a PowerShell todo to the GitHub issue tracker?)

Anyway, I will fix the wording here soon.

Copy link
Contributor Author

@codingthat codingthat Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, cf. 107e961

For the moment, the test runner for [working locally][working-locally] requires Linux.
This track requires Godot version 4.0 or greater.

You can include the installation instructions in this document, but
usually it is better to link to a resource with the official installation
instructions, to prevent the instructions from becoming outdated.
After completing the installation, you can verify if the CLI was installed successfully by running this command in a terminal:

The contents of this document are displayed on the track's documentation
page at `https://exercism.org/docs/tracks/<track>/installation`.
```bash
godot --version
```

See https://exercism.org/docs/building/tracks/docs for more information. -->
## Installing the Exercism GDScript track test runner

You'll need [Godot installed][installation] correctly to use the test runner.

To build and test GDScript scripts for Exercism, Godot will be run in "headless" mode from the CLI.
These instructions currently require Linux and bash.
Copy link
Member

@BNAndras BNAndras Jul 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we sure this requires just Linux? My Mac has /opt available and it can run Linux-based Docker images.

Copy link
Contributor Author

@codingthat codingthat Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no Mac to test on, but if it can be verified to work there we can change it. The local test runner described in this doc, though, doesn't use Docker (it relies on run.sh, which runs Godot directly), so you'd have to install Godot.

Copy link
Member

@BNAndras BNAndras Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, we might want to call the local test runner something else. Within Exercism, a test runner is almost always the online one. That'll certainly cause some confusion down the line for example if a student is asking about running the local tests and we all think they refer to the online test runner.

Copy link
Member

@BNAndras BNAndras Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have access to a M1 Mac so I can check this script out later this week.

Copy link
Contributor Author

@codingthat codingthat Jul 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see some places I've called it simply "test runner" and I could make it "local test runner" to be unambiguous. But if you think that will still be confused with the online one despite "local" everywhere, I'm open to suggestions. I see other tracks don't generally need one because the CLI syntax for testing is a bit more standardized than in the Godot ecosphere.

Maybe "local solution checker"?


### Step 1: Installing the overall test runner infrastructure

To set up for testing, clone [https://github.com/exercism/gdscript-test-runner][gdscript-test-runner] and move its contents to `/opt/exercism/gdscript/test-runner/`:

```sh
git clone https://github.com/exercism/gdscript-test-runner.git
sudo mv gdscript-test-runner/ /opt/exercism/gdscript/test-runner/
```

### Step 2: Downloading the single-exercise test runner script

Assuming you have the `exercism` tool set up and have downloaded at least one GDScript exercise, it should have created a `gdscript` folder under your workspace (as shown by running `exercism configure`) to house the exercises.
Save [the test runner][test-local-gdscript-solution] in this folder and mark the file executable.

## Running tests

With the installation steps done, you should be able start from any exercise directory (e.g., `~/exercism/gdscript/two-fer`) and run the script (living one level up, in `../`) to test your local solution to that exercise:

```sh
../test-local-gdscript-solution.sh
```

[installation]: https://exercism.org/docs/tracks/gdscript/installation
[gdscript-test-runner]: https://github.com/exercism/gdscript-test-runner
[test-local-gdscript-solution]: https://raw.githubusercontent.com/exercism/gdscript-test-runner/refs/heads/main/bin/test-local-gdscript-solution.sh

## Using an IDE

For features like syntax highlighting of GDScript files from, for example, [Visual Studio Code][vscode], you'll need an extension like [godot-tools][godot-tools] installed and activated, and a running debug server.
When you open the Godot GUI and open a project, a debug server automatically runs in the background until you close the project or Godot.

[godot-engine]: https://godotengine.org/
[working-locally]: /docs/using/solving-exercises/working-locally.md
[vscode]: https://code.visualstudio.com/download
[godot-tools]: https://open-vsx.org/vscode/item?itemName=geequlim.godot-tools