Installing Go and setting up VS Code: your workspace

Why this matters

A programmer works with three different things: the language, the editor and the terminal. A beginner mixes them up, and then cannot tell which one is at fault when something fails to work.

Half an hour now, and you will know who to take which trouble to. This is the dull lesson, but it is the only one: after it there is nothing but code.

The whole thing at once

Here is where we are going. A folder with two files:

go-oqu/
└── sabaq-01/
    ├── go.mod
    └── main.go

And the command that runs it:

go run .

Salem, alem!

Everything else in this lesson is how to get there, and what each piece is.

Taking it apart

Three tools, and which is answerable for what

Go is the language itself plus a set of commands. It turns the text you write into a running program. Without it nothing runs at all.

Picture it. A site foreman with a crew. You bring the drawing, he puts up the house from it. Nobody can live in a drawing.

The editor is the window you write text in. By itself it runs nothing and knows nothing about Go until it is helped. We will use VS Code: it is free and works the same on Windows, macOS and Linux.

Picture it. A desk with a lamp, a ruler and decent paper. You can draw on your knee in the dark — just slower, and with mistakes.

The terminal is the window where you give a program orders as text. It is built into VS Code; there is no need to open it separately.

Picture it. The counter where you hand in requests. You write on a slip what needs doing and pass it through.

Remember that split, it saves hours:

• the program will not build and Go complains about your code — the code is at fault;
• there is a red underline in the editor but go run works — that is the extension advising you, not an error;
• the terminal says “command not found” — the problem is the installation, not the program.

Installing Go

Open go.dev/dl. Download the installer for your system: take the latest stable version the page offers — at the time this lesson was written that is go1.27.1. Run it and click through.

Do not unpack the archive by hand into some arbitrary place. The installer puts Go where the system can find it, and writes it into PATH.

PATH is the list of folders the terminal searches for commands. When you type go, the terminal does not scan the whole disk, it looks only in that list. A program installed outside PATH is on the disk but does not exist as far as the terminal is concerned.

Picture it. A courier’s list of addresses. The shop may be one street over, but if it is not on the list the courier comes back and says there is no such place. He does not walk the town, he reads the list.

Close the terminal and open it again — it reads PATH at start-up. Then check:

go version

A line like go version go1.27.1 darwin/arm64 should come back. The last two words are your system and processor type; yours will differ.

Installing the editor

Open code.visualstudio.com, download, install.

An extension is an add-on that teaches the editor something new. Out of the box VS Code knows nothing about Go.

Picture it. A bit in a drill. One drill, and it goes through wood or concrete depending on what you put in the chuck.

One is required. Press Ctrl+Shift+X (⇧⌘X on Mac), type Go into the search, and install the one whose author is Go Team at Google. That is the official one.

The first time you open a .go file, the editor offers Install All at the bottom right. Accept. It fetches several helper programs; the main one is gopls, which suggests as you type, shows errors while you are still writing, and puts your code into the common shape when you save.

Picture it. A proofreader reading over your shoulder. You are still writing the sentence and the pencil has already gone under the typo.

Optionally add Error Lens, which prints the error text on the line itself instead of hiding it under an underline. For a beginner that helps noticeably.

If it did not work. No Install All button — press Ctrl+Shift+P (⌘⇧P on a Mac), type Go: Install/Update Tools, tick everything and confirm. The installer finished but the terminal says command not found: go — close the terminal and the editor completely and open them again: PATH is read at start-up. If that does not help either, restart the computer; on Windows that is usually the cure. If you are on a school or work computer where installing is forbidden, the language lessons up to the server one can be done at go.dev/play in the browser — but from the server lesson on you need your own machine, and it is worth finding that out now rather than in two weeks.

A folder to work in

Go used to demand that code live in one special place. That rule, GOPATH, was dropped long ago: a project is now just a folder. But you need a place of your own, even if Go does not.

Make one folder for the whole course, and a folder per lesson inside it:

• macOS and Linux: ~/go-oqu/sabaq-01
• Windows: %USERPROFILE%\go-oqu\sabaq-01 — that is, inside your own user folder. An ordinary account cannot always write to the root of C:\.

You can make the folder with the mouse, or with a command. On Windows the VS Code terminal opens PowerShell by default, and there the user folder is called $HOME rather than %USERPROFILE%:

cd $HOME
mkdir go-oqu
cd go-oqu

On macOS and Linux the same:

cd ~
mkdir go-oqu
cd go-oqu

Not the Desktop and not Downloads: files get lost among other people’s there, and some systems clear Downloads on their own. Name folders in Latin letters without spaces — a path with spaces now and then breaks a tool, and the second lesson is no place to be debugging that.

Open the folder in the editor: File → Open Folder. Opening the folder rather than a single file matters, or the suggestions will not work.

go mod init: naming the project

Open the terminal inside VS Code — the menu Terminal → New Terminal, or Ctrl + ` (the backtick key, left of the 1). In the lesson folder, run:

go mod init sabaq01

A two-line go.mod file appears beside your code — the project’s name and the Go version. It is the project’s passport: from it Go knows where the project begins and what it is called.

Picture it. The number plate on a house. Without it the postman sees walls but cannot tell where one house ends and the next begins.

Strictly speaking a six-line program runs without it. But without a go.mod the editor runs in a reduced mode: the project’s boundaries are undefined and some of the suggestions disappear. We take modules apart properly when we get to packages.

Why reading is not enough

Said plainly, so you do not waste time.

Reading does not give skill. It prepares the ground: after a lesson it feels as though everything is clear, and that feeling misleads.

Here is why. When you read, you recognise: the line on the screen looks familiar, and the brain takes familiarity for understanding readily enough. But recognising what is written and writing it yourself are different acts, and they are trained separately. The memory that works while you read is a short one: it holds what you are looking at now and lets go of it within days. That is why what was read evaporates — your hands did nothing.

Typing works differently. As you type you retrieve the code from your head instead of identifying it on a page, and the repetition settles into another memory, the one people call muscle memory. It accumulates more slowly but stays for years and asks for no attention: the fingers put in the colon before the equals and close the brace by themselves, they remember the order of func, the name and the brackets — while your head is busy with the problem rather than the syntax. It is the same memory a musician or an athlete has, and it behaves the same way.

None of which means reading is pointless. Both halves are needed and neither replaces the other: reading delivers the information — what a slice is, why append returns a new one — and typing turns information into skill. Without the first you would be guessing; without the second you would only ever recognise other people’s code.

There are no champions who learned boxing from a book. No singer found their voice by reading about voices, and no dancer built a step from a description of one. Programming is no different: reading about code and writing code are two occupations, and the second cannot be replaced by the first.

Hence the rule for the whole course:

1. Solve the exercise in VS Code. The editor underlines the mistake while you are still typing, suggests names, and puts the indentation right when you save. It teaches you as you go — a box on a web page cannot.
2. Run it and see that it works. go run ., and look at the output yourself.
3. Only then, the check on the site. It is not there to find your typo but to confirm the exercise was understood. There are three checks per lesson, and spending one on something the editor would have shown you for nothing is a waste.

The first program

Create a file called main.go in the same folder:

package main

import "fmt"

func main() {
	fmt.Println("Salem, alem!")
}

“Salem, alem!” is Kazakh for “Hello, world” — alem means world. For half a century the first program in any language has greeted the world, and in English it is called Hello, World. We keep the tradition and say it in our own language.

What these six lines say

Let us go through every word. Nothing needs memorising: these lines stand at the top of any Go program, and you will know them by heart after typing them a few times.

package main — a declaration of what kind of file this is. A package is a folder of code with a name. The name main is special: it means “a program you can run”, not “a set of parts for other people’s programs”.

Picture it. A sign on a door. main says ENTRANCE — this is where you come in from the street. A package with any other name is a back room: it has a door, but not for visitors.

import "fmt" — what to bring to the bench with you. fmt, from format, knows how to print text. Leave the import out and the tool is not there, and the program will not build.

Picture it. A tool store and your workbench. import is what you fetched from the store and set down in front of you. Everything else is on the shelves, out of arm’s reach.

func — the start of a function. A function is a written-down order of actions with a name on it. Until it is called, nothing happens.

Picture it. A recipe in a notebook. It lies there and waits. Until somebody starts cooking from it, the kitchen is empty.

main — the name of this function, and it too is special: this is where Go comes in when the program starts. There is exactly one of these per program.

Picture it. The front door of a house. There can be any number of rooms, but you always come in through that one.

() — the round brackets after the name. What the function works on is passed in there. main has nothing inside them: nothing is passed to it, it simply begins.

{ and } — the curly brackets. Everything between them is the body of the function, the part that does something.

Picture it. The walls of a room. { you came in, } you went out. Brackets always come in pairs: there is no wall without its opposite wall.

fmt.Println("Salem, alem!") — prints a line to the terminal. The dot reads as “out of”: take Println out of fmt. The name itself is print line: print a line and move the cursor to the next one.

Picture it. A toolbox and a tool inside it. fmt is the box, Println is the hammer, the dot is the hand reaching in.

Six lines, eight ideas. They are not explained again later in the course — from here you are assumed to know them.

Run it:

go run .

The dot means “everything in this folder”. You could have written go run main.go, but with the dot nothing needs changing once there is more than one file.

The lesson map

Say it in your own words

Answer out loud or on paper without looking. The answers are at the end of the lesson.

1. If you deleted VS Code, would your program stop running?
2. The terminal answers command not found: go. What exactly happened, and where do you look for the cause?
3. What is go.mod for, if a six-line program works without it?

Exercise

Required. Work through the lesson: Go installed, folder made, go run . printing the greeting. Then swap “alem” for your own name and run it again.

Optional.

• Open go.mod and read both lines. What do they say?
• Make a folder sabaq-02 beside it and repeat everything from memory, without looking.
• Delete the line import "fmt" from main.go and run it. Read what Go says, then put it back. Seeing an error on purpose once is worth it.

Where this goes in your blog

Your blog will live in this folder. Every lesson from here starts the same way: a new folder, go mod init, main.go — until the lesson on packages, where we gather it all into one project.

Answers

Sources

• Download and install Go — go.dev
• Visual Studio Code
• The Go extension for VS Code — documentation
• Go Modules Reference — go.dev