Browse Source

A better new_project.sh (#5191)

* A better new_project.sh

* Fix docstrings

* Use single quotes for anything not shown to user

* Missed this docstring

* Simplify get_git_username()

Thanks @vomindoraan

* chmod +x

* Add docstring for print_error()

* Break up git username call into multiple lines

* Use with statement here

* Conform to PEP 8 even more

* Turn it back into a shell script

* chmod +x again

* Update docs to reflect new keyboard generator usage

* Tweak wording slightly

* Trim trailing whitespace

* Don't actually need to escape the newlines here

* As I suspected, you can pass shift a number

* Prepend ./ to match the other code block

* Minor syntax tweaks

* The username token has changed

* Replace name in the readme too

* Make some reasonable assumptions about the presence of Git
pjones-keymap
fauxpark 1 month ago
parent
commit
53c51f1d16

+ 7
- 5
docs/hand_wire.md View File

@@ -198,15 +198,17 @@ From here, you should have a working keyboard once you program a firmware. Befor
198 198
 
199 199
 To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/) (paid) or [Visual Studio Code](https://code.visualstudio.com) (free).
200 200
 
201
-The first thing we're going to do is create a new project using the script in the root directory of the firmware. In your terminal, run this command with `<project_name>` replaced by the name of your project - it'll need to be different from any other project in the `keyboards/` folder:
201
+The first thing we're going to do is create a new keyboard. In your terminal, run this command, which will ask you some questions and generate a basic keyboard project:
202 202
 
203 203
 ```
204
-    util/new_project.sh <project_name>
204
+./util/new_keyboard.sh
205 205
 ```
206 206
 
207 207
 You'll want to navigate to the `keyboards/<project_name>/` folder by typing, like the print-out from the script specifies:
208 208
 
209
-    cd keyboards/<project_name>
209
+```
210
+cd keyboards/<project_name>
211
+```
210 212
 
211 213
 ### `config.h`
212 214
 
@@ -326,7 +328,7 @@ Carefully flip your keyboard over, open up a new text document, and try typing -
326 328
 2. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not.
327 329
 3. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work.
328 330
 4. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides.
329
-5. Check the <project_name>.h file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable.
331
+5. Check the `<project_name>.h` file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable.
330 332
 6. Check to make sure you actually compiled the firmware and flashed the Teensy correctly. Unless you got error messages in the terminal, or a pop-up during flashing, you probably did everything correctly.
331 333
 
332 334
 If you've done all of these things, keep in mind that sometimes you might have had multiple things affecting the keyswitch, so it doesn't hurt to test the keyswitch by shorting it out at the end.
@@ -335,4 +337,4 @@ If you've done all of these things, keep in mind that sometimes you might have h
335 337
 
336 338
 Now that you have a working board, it's time to get things in their permanent positions. I've often used liberal amounts of hot glue to secure and insulate things, so if that's your style, start spreading that stuff like butter. Otherwise, double-sided tape is always an elegant solution, and electrical tape is a distant second. Due to the nature of these builds, a lot of this part is up to you and how you planned (or didn't plan) things out.
337 339
 
338
-There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different project (Planck, Clueboard, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb)
340
+There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different keyboards (Planck, Clueboard, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb)

+ 20
- 8
docs/hardware_avr.md View File

@@ -6,14 +6,26 @@ If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_
6 6
 
7 7
 ## Adding Your AVR Keyboard to QMK
8 8
 
9
-QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started run the `util/new_project.sh` script:
10
-
11
-```bash
12
-$ util/new_project.sh my_awesome_keyboard
13
-######################################################
14
-# /keyboards/my_awesome_keyboard project created. To start
15
-# working on things, cd into keyboards/my_awesome_keyboard
16
-######################################################
9
+QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started, run the `util/new_keyboard.sh` script:
10
+
11
+```
12
+$ ./util/new_keyboard.sh
13
+Generating a new QMK keyboard directory
14
+
15
+Keyboard Name: mycoolkb
16
+Keyboard Type [avr]: 
17
+Your Name [John Smith]: 
18
+
19
+Copying base template files... done
20
+Copying avr template files... done
21
+Renaming keyboard files... done
22
+Replacing %KEYBOARD% with mycoolkb... done
23
+Replacing %YOUR_NAME% with John Smith... done
24
+
25
+Created a new keyboard called mycoolkb.
26
+
27
+To start working on things, cd into keyboards/mycoolkb,
28
+or open the directory in your favourite text editor.
17 29
 ```
18 30
 
19 31
 This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard.

+ 17
- 7
docs/porting_your_keyboard_to_qmk_(arm_and_other_chibios_cpus).md View File

@@ -1,14 +1,24 @@
1
-Setting up your ARM based PCB is a little more involved than an Atmel MCU, but is easy enough. Start by using `util/new_project.sh <keyboard>` to create a new project:
1
+Setting up your ARM based PCB is a little more involved than an Atmel MCU, but is easy enough. Start by running `util/new_keyboard.sh`:
2 2
 
3 3
 ```
4
-$ util/new_project.sh simontester
5
-######################################################
6
-# /keyboards/simontester project created. To start
7
-# working on things, cd into keyboards/simontester
8
-######################################################
9
-```
4
+$ ./util/new_keyboard.sh
5
+Generating a new QMK keyboard directory
6
+
7
+Keyboard Name: mycoolkb
8
+Keyboard Type [avr]: 
9
+Your Name [John Smith]: 
10 10
 
11
+Copying base template files... done
12
+Copying avr template files... done
13
+Renaming keyboard files... done
14
+Replacing %KEYBOARD% with mycoolkb... done
15
+Replacing %YOUR_NAME% with John Smith... done
11 16
 
17
+Created a new keyboard called mycoolkb.
18
+
19
+To start working on things, cd into keyboards/mycoolkb,
20
+or open the directory in your favourite text editor.
21
+```
12 22
 
13 23
 # END OF NEW ARM DOC, OLD ATMEL DOC FOLLOWS
14 24
 

+ 159
- 0
util/new_keyboard.sh View File

@@ -0,0 +1,159 @@
1
+#!/bin/bash
2
+
3
+# This script generates a new keyboard directory under keyboards/,
4
+# and copies the template files from quantum/template/ into it.
5
+
6
+# Print an error message with the word "ERROR" in red.
7
+echo_error() {
8
+    echo -e "[\033[0;91mERROR\033[m]: $1"
9
+}
10
+
11
+# Print a message in bold.
12
+echo_bold() {
13
+    echo -e "\033[1m$1\033[m"
14
+}
15
+
16
+# Prompt the user for information, showing the default value in brackets.
17
+prompt() {
18
+    local message="$1"
19
+    local default="$2"
20
+
21
+    [ -n "$default" ] && message+=" [$default]"
22
+    message+=": "
23
+
24
+    read -rp "$message" prompt_return
25
+    [ -z "$prompt_return" ] && prompt_return="$default"
26
+}
27
+
28
+# Grab a username from Git config.
29
+set_git_username() {
30
+    git_username="$(git config --get user.name)"
31
+}
32
+
33
+# Copy the template files to the new keyboard directory.
34
+copy_templates() {
35
+    echo -n "Copying base template files..."
36
+    cp -r "quantum/template/base" "${keyboard_dir}"
37
+    echo " done"
38
+
39
+    echo -n "Copying $keyboard_type template files..."
40
+    cp -r "quantum/template/${keyboard_type}/." "${keyboard_dir}"
41
+    echo " done"
42
+
43
+    echo -n "Renaming keyboard files..."
44
+    mv "${keyboard_dir}/template.c" "${keyboard_dir}/${keyboard_name}.c"
45
+    mv "${keyboard_dir}/template.h" "${keyboard_dir}/${keyboard_name}.h"
46
+    echo " done"
47
+}
48
+
49
+# Set the inplace editing parameter for sed.
50
+# macOS/BSD sed expects a file extension immediately following -i.
51
+set_sed_i() {
52
+    sed_i=(-i)
53
+
54
+    case $(uname -a) in
55
+        *Darwin*) sed_i=(-i "")
56
+    esac
57
+}
58
+
59
+# Replace a token with a value in the given list of files.
60
+replace_placeholders() {
61
+    local replace_token="$1"
62
+    local replace_value="$2"
63
+    shift 2
64
+    local replace_filenames=("$@")
65
+
66
+    echo -n "Replacing $replace_token with $replace_value..."
67
+    for replace_filename in "${replace_filenames[@]}"; do
68
+        sed "${sed_i[@]}" -e "s/${replace_token}/${replace_value}/g" "$replace_filename"
69
+    done
70
+    echo " done"
71
+}
72
+
73
+# Replace %KEYBOARD% with the keyboard name.
74
+replace_keyboard_placeholders() {
75
+    local replace_keyboard_filenames=(
76
+        "${keyboard_dir}/config.h"
77
+        "${keyboard_dir}/readme.md"
78
+        "${keyboard_dir}/${keyboard_name}.c"
79
+        "${keyboard_dir}/keymaps/default/readme.md"
80
+    )
81
+    replace_placeholders "%KEYBOARD%" "$keyboard_name" "${replace_keyboard_filenames[@]}"
82
+}
83
+
84
+# Replace %YOUR_NAME% with the username.
85
+replace_name_placeholders() {
86
+    local replace_name_filenames=(
87
+        "${keyboard_dir}/config.h"
88
+        "${keyboard_dir}/readme.md"
89
+        "${keyboard_dir}/${keyboard_name}.c"
90
+        "${keyboard_dir}/${keyboard_name}.h"
91
+        "${keyboard_dir}/keymaps/default/config.h"
92
+        "${keyboard_dir}/keymaps/default/keymap.c"
93
+    )
94
+    replace_placeholders "%YOUR_NAME%" "$username" "${replace_name_filenames[@]}"
95
+}
96
+
97
+# Check if an array contains an element.
98
+array_contains() {
99
+    local e match="$1"
100
+    shift
101
+    for e; do
102
+        [[ "$e" == "$match" ]] && return 0;
103
+    done
104
+
105
+    return 1
106
+}
107
+
108
+# If we've been started from util/, we want to be in qmk_firmware/
109
+[[ "$PWD" == *util ]] && cd ..
110
+
111
+# The root qmk_firmware/ directory should have a subdirectory called quantum/
112
+if [ ! -d "quantum" ]; then
113
+    echo_error "Could not detect the QMK firmware directory!"
114
+    echo_error "Are you sure you're in the right place?"
115
+    exit 1
116
+fi
117
+
118
+echo_bold "Generating a new QMK keyboard directory"
119
+echo
120
+
121
+# Keyboard name is required, so keep prompting until we get one
122
+while [ -z "$keyboard_name" ]; do
123
+    prompt "Keyboard Name" ""
124
+    keyboard_name=$prompt_return
125
+done
126
+
127
+keyboard_dir="keyboards/$keyboard_name"
128
+
129
+if [ -d "$keyboard_dir" ]; then
130
+    echo_error "Keyboard $keyboard_name already exists!"
131
+    exit 1
132
+fi
133
+
134
+KEYBOARD_TYPES=("avr" "ps2avrgb")
135
+
136
+prompt "Keyboard Type" "avr"
137
+keyboard_type=$prompt_return
138
+
139
+if ! array_contains "$keyboard_type" "${KEYBOARD_TYPES[@]}"; then
140
+    echo_error "Keyboard type must be one of: ${KEYBOARD_TYPES[*]}"
141
+    exit 1
142
+fi
143
+
144
+set_git_username
145
+prompt "Your Name" "$git_username"
146
+username=$prompt_return
147
+
148
+echo
149
+
150
+copy_templates
151
+set_sed_i
152
+replace_keyboard_placeholders
153
+[ -n "$username" ] && replace_name_placeholders
154
+
155
+echo
156
+echo_bold "Created a new keyboard called $keyboard_name."
157
+echo
158
+echo_bold "To start working on things, cd into keyboards/$keyboard_name,"
159
+echo_bold "or open the directory in your favourite text editor."

+ 0
- 70
util/new_project.sh View File

@@ -1,70 +0,0 @@
1
-#!/bin/sh
2
-# Script to make a new quantum project
3
-# Jack Humbert 2015
4
-
5
-KEYBOARD=$1
6
-KEYBOARD_TYPE=$2
7
-
8
-if [ -z "$KEYBOARD" ]; then
9
-    echo "Usage:   $0 <keyboard_name> <keyboard_type>"
10
-    echo "Example: $0 gh60 avr"
11
-    echo "Example: $0 bfake ps2avrgb"
12
-    exit 1
13
-elif [ -z "$KEYBOARD_TYPE" ]; then
14
-  KEYBOARD_TYPE=avr
15
-fi
16
-
17
-if [ "$KEYBOARD_TYPE" != "avr" ] && [ "$KEYBOARD_TYPE" != "ps2avrgb" ]; then
18
-  echo "Invalid keyboard type target"
19
-  exit 1
20
-fi
21
-
22
-if [ -e "keyboards/$1" ]; then
23
-	echo "Error! keyboards/$1 already exists!"
24
-	exit 1
25
-fi
26
-
27
-cd "$(dirname "$0")/.." || exit
28
-
29
-KEYBOARD_NAME=$(basename "$1")
30
-KEYBOARD_NAME_UPPERCASE=$(echo "$KEYBOARD_NAME" | awk '{print toupper($0)}')
31
-NEW_KBD=keyboards/${KEYBOARD}
32
-
33
-
34
-cp -r quantum/template/base "$NEW_KBD"
35
-cp -r "quantum/template/$KEYBOARD_TYPE/." "$NEW_KBD"
36
-
37
-mv "${NEW_KBD}/template.c" "${NEW_KBD}/${KEYBOARD_NAME}.c"
38
-mv "${NEW_KBD}/template.h" "${NEW_KBD}/${KEYBOARD_NAME}.h"
39
-find "${NEW_KBD}" -type f -exec sed -i '' -e "s;%KEYBOARD%;${KEYBOARD_NAME};g" {} \;
40
-find "${NEW_KBD}" -type f -exec sed -i '' -e "s;%KEYBOARD_UPPERCASE%;${KEYBOARD_NAME_UPPERCASE};g" {} \;
41
-
42
-GIT=$(whereis git)
43
-if [ "$GIT" != "" ]; then
44
-  IS_GIT_REPO=$($GIT log >>/dev/null 2>&1; echo $?)
45
-  if [ "$IS_GIT_REPO" -eq 0 ]; then
46
-    ID="$($GIT config --get user.name)"
47
-    read -rp "What is your name? [$ID] " YOUR_NAME
48
-    if [ -n "$YOUR_NAME" ]; then
49
-      ID=$YOUR_NAME
50
-    fi
51
-    echo "Using $ID as user name"
52
-
53
-    for i in "$NEW_KBD/config.h" \
54
-             "$NEW_KBD/$KEYBOARD_NAME.c" \
55
-             "$NEW_KBD/$KEYBOARD_NAME.h" \
56
-             "$NEW_KBD/keymaps/default/config.h" \
57
-             "$NEW_KBD/keymaps/default/keymap.c"
58
-    do
59
-      awk -v id="$ID" '{sub(/%YOUR_NAME%/,id); print}' < "$i" > "$i.$$"
60
-      mv "$i.$$" "$i"
61
-    done
62
-  fi
63
-fi
64
-
65
-cat <<-EOF
66
-######################################################
67
-# $NEW_KBD project created. To start
68
-# working on things, cd into $NEW_KBD
69
-######################################################
70
-EOF

Loading…
Cancel
Save