Linux build guide.md

x. Git Terminology

Some quick definitions that will help you understand what's going on here:

1. A branch is a line of development - maybe a new version, or a new feature that someone is working on. They can be merged back together later.
2. A git clone fetches all items that make up a remote project and copies them locally into a new, empty directory on your machine.
3. A commit is a specific point in the git history - effectively, a contribution to a branch, or a change affecting one of more chunks of the code.
4. A git checkout is when you switch from one part of the code to another, such as between branches or back and forth through the commit history.
5. A git fetch finds out what the current HEAD is of whatever you have checked out, and goes and gets any missing objects (files, code, images) for you.
6. The HEAD is the tip of whatever branch you currently have checked out. If you've checked out a commit that isn't the HEAD, you have a detached HEAD
7. A git merge weaves new objects (mostly code, but not exclusively) into your local copy of the project.
8. A git pull is a bit like fetch but it immediately writes any changes into your local copy without any further debate - effectively, git fetch followed by git merge.
9. A tag is a pointer to a specific commit, frequently used to label a particular release ("the code for version xyz stopped at this point).

There's an awful lot more to git than that, but that will help with these instructions.

4. Build Kodi

4.0. Make sure you've got the latest code, and select what version to build

If you've only just cloned Kodi as above, then you have the whole code base, and can build any version that's contained in it, so you can carry on. If, however, you cloned some time ago, there will inevitably be new commits that don't yet exist on your machine, and you should really bring your code up to date to make sure you've got all the latest changes. At this point, then:

1. If you're happy to sit at the tip of the master branch, and haven't moved from that (more on this in a moment), then a simple git pull will bring you up to date.
2. If you've made any changes to your local code, then git fetch will get the latest updates for you (but won't switch you away from wherever you are in the history of the code, such as your current tag), as will git checkout master && git pull (which will also move you back to the very latest commit as in option 1).
3. And, if it all gets too much, you could delete the directory and run git clone again. A tad dramatic, but effective!

So, back to that comment about "the tip of the master branch". By default, you're sitting at the latest code commit (in git terms, the HEAD of the master branch), so building at this point will give you the very latest and greatest version of Kodi possible - potentially with bugs and instabilities, as it's not yet ready for release.

If you want to build a specific release of Kodi, then, you need to wind the code backwards to that specific point in time. The key to this is tags: these are pointers to specific bits of the project ("commits") that are usually used to represent the point at which version X was declared "done".

git tag -l will list all available tags.

git checkout tags/<tag> will then move you to the commit specified by that tag - so, to specifically build 20.3 (for example), you'd use git checkout tags/20.3-Nexus to jump to that point in history.

You can move back and forth between any tags that existed when you pulled the code - so, anything in that tag list you just saw. As time moves on, new tags will inevitably be created, and you'll get these as and when you update your local copy of the code.

4.1. Configure build

So, you're now sitting where you want to, and are ready to build the specific version you're after.

If you get a Could NOT find... error message during CMake configuration step, take a note of the missing dependencies and either install them from repositories (if available) or build the missing dependencies manually.

.... wiki continues

You could delete the directory and run git clone again. A tad dramatic, but effective.

I'm not sure this should be the first option :D

It should be noted though that in case of any build problems at all, the cmake build directory should definitely be nuked. Might be already in the guide though.

If you've done anything else, then git fetch will update your code (but leave you at this tag),

Is it clear to people what "update your code" would mean here? I'm having trouble interpreting that, but I might already know "too much".

If you want to build a specific version

a specific release, rather?

The key to this is tags: these are pointers to specific bits of the code

specific bits of the repository? specific snapshots of the code?

@yol Thanks for that - I've added a "git primer" to help with the terminology and made a few changes.

Personally, I'm unconvinced that ordinary, drive-by users should be doing this, as it's a whole new world of support. Even the git terminology is getting complicated, and I haven't scratched the surface of what's going on (even if I've got it all right!).