Qmk_firmware: Make is too complex

[lindhe]

Hi. I'm not very active here, but still a long-time contributor to this project. I sync my fork a handful of times a year, and try to keep stuff up-to-date with what you do. A few years ago, you changed how the make command parse stuff, and that really threw a wrench into things for me since I was not made aware of this breaking change. I found the commit that introduced it, and started chatting with someone that was very helpful and we eventually got the right make command.

I'm a software engineer with a Master's degree in CS/engineering. That does not make me the best programmer in the world, but I'm for sure not unfamiliar around computers or how to compile programs. Yet, I get stuck on this _every single time_ I try to compile my layout in this project. Today, I tried to compile my layout. And sure enough, I didn't remember how to do it. So I tried reverse searching my bash history to see what I ran last. But turns out I've reinstalled recently, so I couldn't find the command. I experimentally tried a few but no go.

make swedish-lindhe
make ergodox/swedish-lindhe
make ergodox_ez/swedish-lindhe
make teensy/ergodox_ez/swedish-lindhe
make teensy/ergodox_ez:swedish-lindhe
make teensy/ergodox:swedish-lindhe
make layouts/community/ergodox:swedish-lindhe
make community/ergodox:swedish-lindhe

They all end up similar to this:

> make swedish-lindhe                          
QMK Firmware preonic-1.0
make: *** No rule to make target 'swedish-lindhe'. Stop.
|
|  QMK's make format recently changed to use folder locations and colons:
|     make project_folder:keymap[:target]
|  Examples:
|     make planck/rev4:default:dfu
|     make planck:default
|

Luckily, I'm good with backups. So I went to the backup of my previous installation, and found make ergodox_ez:swedish-lindhe which did the trick (at least after installing a few dependencies, which is perfectly normal). But not being able to figure out the make command, even after reading the help text that make gives, that's bad.

I bet I'm not the only one, because people don't dare to look so stupid as not being able to compile a program. But I'll gladly admit defeat and say that this should be way simpler than it is.

I open this issue mainly as a discussion thread, and hopefully we can find a reasonable solution to this together.

[cubimon]

I had the same issue when I started with qmk, but honestly it is super easy, just read the docs. It explicitly says make <my_keyboard>:<my_keymap> and even has an example make planck/rev5:xyverz. Btw the documentation is awesome.

[lindhe]

It's certainly not helped by the fact that I compile only a few times a year – have to give you that. If the docs are good, perhaps only the make help text needs to be refurbished? Because project folder says nothing to me, and I still have to guess if they mean teensy, ergodox or ergodox_ez.

[drashna]

Given the commands that you were trying to use, it sounds more like your repo was several years out of date.

We switched from having makefile in each folder, as well as the / divider for commands several years ago (when we introduced community layouts, in fact).

But yeah, the project_folder should be whatever is under keyboards/. For the ergodox ez, that would definitely be the ergodox_ez. Additionally, most of the keyboards do have readmes with the correct commands. It's a bit out of date, but the ergodox ez still does:
https://github.com/qmk/qmk_firmware/tree/master/keyboards/ergodox_ez#ergodox-ez

However, I can see how the current documentation could be confusing, especially if you're not used to it.

[Erovia]

You could give a try to the CLI.
After installing, I'd execute these commands:

// this is only needed, if you don't want to specifiy them each time
qmk config user.keyboard=ergodox_ez
qmk config  user.keymap=swedish-lindhe

// from now on, you can compile your keymap with this one command:
qmk compile