Create ARM64 assembly track's docs, linter, and editor config. (#51)

* add README with plans

* fix various problems with docs and QEMU-fy the makefile

* README needed a clarification, scratchpad info isn't needed but will be recorded

* README TODOs have been stripped and redone

* Apply suggestions from code review

The other changes seem to require manual intervention and discussion. Will get to that in a bit.

Co-authored-by: Derk-Jan Karrenbeld <[email protected]>

* add 'we' instead of 'I' along with suggested edit

* Hold off on the help note based on suggestions in #51

I don't think I'm ready for that yet. The MIPS assembly track was doing it though but giving it thought seems to show my situation is different.

* fix up INSTALLATION instructions

* edit links into reflinks + missing newline added to a config

* append a lone reflink I forgot to change

Co-authored-by: Derk-Jan Karrenbeld <[email protected]>

README.md

@@ -3,3 +3,24 @@
 [![Build Status](https://travis-ci.org/exercism/arm64-assembly.svg?branch=master)](https://travis-ci.org/exercism/arm64-assembly)
 
 Exercism exercises in ARM64 Assembly.
+
+## Assembler
+
+GNU Assembler (gas) is used for this track.
+
+## Testing
+
+Unity is a simple unit testing framework for C used by this track.
+Using a framework written in C instead of assembly language is easier to understand.
+It also shows how parameters are passed when calling assembly routines from C.
+
+## Variant and Calling Conventions
+
+This is probably going to use the ARMv8.0-A profile which is a good default.
+This track is also probably going to use the ARM default calling convention to spare mentors from trouble.
+
+## Contributing Guide
+
+Please see the [contributing guide][contributing-guide]
+
+[contributing-guide]: https://github.com/exercism/x-api/blob/master/CONTRIBUTING.md#the-exercise-data

config.json

@@ -48,5 +48,18 @@
   },
   "concepts": [],
   "key_features": [],
-  "tags": []
+  "tags": [
+    "paradigm/imperative",
+    "paradigm/procedural",
+    "typing/static",
+    "typing/weak",
+    "execution_mode/compiled",
+    "platform/android",
+    "platform/ios",
+    "platform/mac",
+    "platform/linux",
+    "runtime/standalone_executable",
+    "used_for/embedded_systems",
+    "used_for/mobile"
+  ]
 }

docs/ABOUT.md

@@ -1,2 +1,7 @@
 # About
 
+ARM64/AArch64 assembly is the 64-bit version of the ARM instruction set.
+It is based on the ARMv7 instruction set, which is in turn loosely based off the legacy ARM Classic instruction sets.
+
+This track involves programming in ARM64 assembly language, assembled and run on a cross-platform simulator.
+

docs/INSTALLATION.md

@@ -1,2 +1,13 @@
 # Installation
 
+Install the essential build tools, the QEMU emulator, and the GCC ARM64 cross-toolchain to test your code.
+
+```shell
+sudo apt install build-essential qemu-user qemu-user-static binutils-aarch64-linux-gnu gcc-aarch64-linux-gnu
+```
+
+The makefile in the exercise directory should be able to handle the rest.
+
+## Special note for Windows users
+
+Use Windows Subsystem for Linux 2 with an Ubuntu image to do the same steps listed above.

docs/LEARNING.md

@@ -1,2 +1,13 @@
 # Learning
 
+ARM64 assembly is a simple assembly language. 
+You might be able to start off with [a reference card][reference-card].
+
+ARM also provides [digital reference][official-reference] on the ARM64 (AArch64/ARMv8) architecture.
+
+We hope you enjoy learning ARM assembly and working through the exercises.
+
+This is a gateway to getting to know your phone or ARM64 based development hardware (the more recent Raspberry Pi models are an example).
+
+[reference-card]: https://courses.cs.washington.edu/courses/cse469/19wi/arm64.pdf
+[official-reference]: https://developer.arm.com/documentation

docs/RESOURCES.md

@@ -1,2 +1,12 @@
 # Resources
 
+- [ARM64 reference card][reference-card]
+- [Official ARM documentation][official-reference]
+- [The GAS Manual][gas-manual]
+- [The GAS AArch64 Specifics Section][gas-aarch64-specifics]
+
+
+[reference-card]: https://courses.cs.washington.edu/courses/cse469/19wi/arm64.pdf
+[official-reference]: https://developer.arm.com/documentation
+[gas-manual]: https://sourceware.org/binutils/docs/as/
+[gas-aarch64-specifics]: https://sourceware.org/binutils/docs/as/AArch64_002dDependent.html#AArch64_002dDependent

docs/SNIPPET.txt

@@ -0,0 +1,13 @@
+.section .rodata
+msg: .string "Assembly is awesome!\n"
+
+.text
+.global main
+main:
+    adrp x0, msg
+    add x0, x0, :lo12:msg
+    stp x29, x30, [sp]
+    bl printf
+    ldp x29, x30, [sp]
+    mov x0, #0
+    ret                     

docs/TESTS.md

@@ -1,2 +1,17 @@
 # Tests
 
+## Running Tests
+
+To run the tests, execute the following command:
+
+```bash
+make
+```
+
+## Solving the exercise
+
+Solving an exercise means making all its tests pass.
+By default, only one test (the first one) is executed when you run the tests.
+This is intentional, as it allows you to focus on just making that one test pass.
+Once it passes, you can enable the next test by removing the `TEST_IGNORE()` line.
+When all tests have been enabled and your implementation makes them all pass, you'll have solved the exercise!

docs/config.json

@@ -1,3 +1,33 @@
+
 {
-  "docs": []
+  "docs": [
+    {
+      "uuid": "3625b605-b556-4bcf-87da-77f06e493deb",
+      "slug": "installation",
+      "path": "docs/INSTALLATION.md",
+      "title": "Installing ARM64 Assembly locally",
+      "blurb": "Learn how to install ARM64 Assembly locally to solve Exercism's exercises on your own machine"
+    },
+    {
+      "uuid": "3a09769c-f5ad-4e3a-912a-b06ba6cf604b",
+      "slug": "learning",
+      "path": "docs/LEARNING.md",
+      "title": "How to learn ARM64 Assembly",
+      "blurb": "An overview of how to get started from scratch with ARM64 Assembly"
+    },
+    {
+      "uuid": "292b3fa9-45dd-43ec-8528-d3bf442200a4",
+      "slug": "tests",
+      "path": "docs/TESTS.md",
+      "title": "Testing on the ARM64 Assembly track",
+      "blurb": "Learn how to test your ARM64 Assembly exercises on Exercism"
+    },
+    {
+      "uuid": "d4066012-de8c-4c28-89eb-f68dbd075444",
+      "slug": "resources",
+      "path": "docs/RESOURCES.md",
+      "title": "Useful ARM64 Assembly resources",
+      "blurb": "A collection of useful resources to help you master ARM64 Assembly"
+    }
+  ]
 }

exercises/practice/hello-world/Makefile

@@ -1,4 +1,5 @@
-AS = as
+AS = aarch64-linux-gnu-as
+CC = aarch64-linux-gnu-gcc
 
 CFLAGS = -g -Wall -Wextra -pedantic -Werror
 LDFLAGS =
@@ -15,7 +16,7 @@ ALL_OBJS = $(filter-out example.o,$(C_OBJS) $(AS_OBJS) vendor/unity.o)
 CC_CMD = $(CC) $(ALL_CFLAGS) -c -o $@ $<
 
 all: tests
-	@./$<
+	qemu-aarch64 -L /usr/aarch64-linux-gnu ./$<
 
 tests: $(ALL_OBJS)
 	@$(CC) $(ALL_CFLAGS) $(ALL_LDFLAGS) -o $@ $(ALL_OBJS)

exercises/shared/.docs/help.md

@@ -0,0 +1,9 @@
+# Help
+
+To get help if you're having trouble, you can use one of the following resources:
+
+- [ARM64 reference card](https://courses.cs.washington.edu/courses/cse469/19wi/arm64.pdf)
+- [Official ARM documentation](https://developer.arm.com/documentation)
+- [The GAS Manual](https://sourceware.org/binutils/docs/as/)
+- [The GAS AArch64 Specifics Section](https://sourceware.org/binutils/docs/as/AArch64_002dDependent.html#AArch64_002dDependent)
+- [StackOverflow](http://stackoverflow.com) can be used to search for your problem and see if it has been answered already. You can also ask and answer questions.

exercises/shared/.docs/tests.md

@@ -0,0 +1,15 @@
+# Tests
+
+To run the tests, execute the following command:
+
+```bash
+make
+```
+
+## Skipped tests
+
+Solving an exercise means making all its tests pass.
+By default, only one test (the first one) is executed when you run the tests.
+This is intentional, as it allows you to focus on just making that one test pass.
+Once it passes, you can enable the next test by removing the `TEST_IGNORE()` line.
+When all tests have been enabled and your implementation makes them all pass, you'll have solved the exercise!