Skip to content
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.

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

Update and try to clarify the CLI installation on Linux #8783

Merged
merged 3 commits into from
Apr 27, 2020
Merged
Changes from all commits
Commits
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
17 changes: 14 additions & 3 deletions docs/newbs_getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,14 @@ After Homebrew is installed run these commands:

You will need to install Git and Python. It's very likely that you already have both, but if not, one of the following commands should install them:

* Debian / Ubuntu / Devuan: `apt-get install git python3 && python3 -m pip install qmk`
* Fedora / Red Hat / CentOS: `yum install git python3 && python3 -m pip install qmk`
* Arch: `yay -S qmk` (or use any other AUR Helper)
* Debian / Ubuntu / Devuan: `sudo apt install git python3 python3-pip`
* Fedora / Red Hat / CentOS: `sudo yum install git python3 python3-pip`
* Arch / Manjaro: `sudo pacman -S git python python-pip python-setuptools libffi`


Install the global CLI to bootstrap your system:

`python3 -m pip install --user qmk` (on Arch-based distros you can also try the `qmk` package from AUR (**note**: it's maintained by a community member): `yay -S qmk`)
Comment on lines +71 to +76
Copy link
Member

Choose a reason for hiding this comment

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

I'm torn on how we handle arch here. It's a better user experience if they simply install qmk from AUR, but this implies that they have to install some things manually first. Also, why does libffi need to be installed manually?

Copy link
Member Author

Choose a reason for hiding this comment

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

The problem I wanted to solve: we do not control the AUR package, @Curry does, but nobody can expect him to keep up with the releases.
We do have control over the PYPI package.

So I'd rather leave the decision to the users.

libffi: It wasn't pulled in as a dependency for any of the packages and the pip installation fails without it as one of the modules requires it.

Copy link
Member

Choose a reason for hiding this comment

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

Maybe we could work with @Curry to get direct access and setup a pipeline for releases. It's a direction I'd like to go anyway (for example I plan to auto-update the homebrew update once I figure out how.)

Copy link
Contributor

Choose a reason for hiding this comment

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

I have added libffi to the dependencies, so in-case that package isn't installed, it will be installed with the qmk package.

Copy link
Member Author

Choose a reason for hiding this comment

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

I can see that happening in the (near) future, but for now I'm focusing fixing our current docs, so less user stuck following the getting started guide.


## 3. Run QMK Setup :id=set-up-qmk

Expand All @@ -78,6 +83,12 @@ After installing QMK you can set it up with this command:

In most situations you will want to answer Yes to all of the prompts.

?>**Note on Debian, Ubuntu and their derivatives**:
It's possible, that you will get an error saying something like: `bash: qmk: command not found`.
This is due to a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155) Debian introduced with their Bash 4.4 release, which removed `$HOME/.local/bin` from the PATH. This bug was later fixed on Debian and Ubuntu.
Sadly, Ubuntu reitroduced this bug and is [yet to fix it](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562).
Luckily, the fix is easy. Run this as your user: `echo "PATH=$HOME/.local/bin:$PATH" >> $HOME/.bashrc && source $HOME/.bashrc`

?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup <github_username>/qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message.

## 4. Test Your Build Environment
Expand Down