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
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add track installation instructions #97

Changes from all commits
Commits
Show all changes
3 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
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
56 changes: 47 additions & 9 deletions docs/INSTALLATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,53 @@
# Installation

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

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

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.


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.
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.

### Step 1: Installing the overall test runner infrastructure
Copy link
Member

Choose a reason for hiding this comment

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

But yes, this part should be here


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
Copy link
Member

Choose a reason for hiding this comment

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

This part you actually don't have to include at all, since the user is expected to follow the general exercism instructions

Copy link
Contributor Author

@codingthat codingthat May 2, 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 confused — these aren't part of the general exercism instructions... local native Linux students will need to follow this as part of the installation, and it's not covered elsewhere.

Copy link
Member

Choose a reason for hiding this comment

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

Wait my bad, didn't read to carefully, yes this should be here. You are right


Assuming you have the `exercism` tool set up and have downloaded at least one GDScript exercise, it should have created an `exercism/gdscript` folder to house the exercises.
Save [the test runner][test-local-gdscript-solution] in this folder and mark the file executable.

## Running tests
Copy link
Member

Choose a reason for hiding this comment

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

And this part should be in TESTS.md

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Lines 32-33 are still installation-related, though. You need to do this just once, to be able to test any exercise after that.

We can duplicate it over in TESTS.md if you want, but, without the previous step it won't work. So, in TESTS.md I can link to step 1 and duplicate step 2, if you want (but I'm not clear why).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Like, Step 1 is needed for students and track maintainers. Step 2 is an installation step that only students need.

Copy link
Member

Choose a reason for hiding this comment

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

I only marked line 35, but it seemingly also shows the lines above. But yes, 32-33 should be here


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 syntax checking of GDScript files from, for example, [Visual Studio Code][vscode], you'll need to keep the Godot GUI running with a project open in order to activate the debug server, and an extension like [godot-tools][godot-tools] installed and activated.

[godot-engine]: https://godotengine.org/
[vscode]: https://code.visualstudio.com/download
[godot-tools]: https://open-vsx.org/vscode/item?itemName=geequlim.godot-tools