From e09b3797efbe2ef7ad461582ce90c4e9218032a6 Mon Sep 17 00:00:00 2001 From: MegaMech Date: Sun, 14 Jan 2024 14:32:13 -0700 Subject: [PATCH] More docs (#543) * More docs --- Makefile | 1 + docs/basics/BUILD_WINDOWS.md | 3 +- docs/basics/actors.md | 2 + docs/basics/actorsmenu.md | 77 +++++++++++ .../{Basic Concepts.md => basicconcepts.md} | 9 +- docs/basics/basicsmenu.md | 125 ++++++++++++++++++ docs/basics/compiling.md | 80 ++++++----- docs/basics/courses.md | 2 + docs/basics/coursesmenu.md | 77 +++++++++++ docs/basics/menu.html | 68 ++++++++++ docs/basics/placeholder.png | Bin 0 -> 6761 bytes docs/basics/terminology.md | 7 + 12 files changed, 410 insertions(+), 41 deletions(-) create mode 100644 docs/basics/actors.md create mode 100644 docs/basics/actorsmenu.md rename docs/basics/{Basic Concepts.md => basicconcepts.md} (86%) create mode 100644 docs/basics/basicsmenu.md create mode 100644 docs/basics/courses.md create mode 100644 docs/basics/coursesmenu.md create mode 100644 docs/basics/menu.html create mode 100644 docs/basics/placeholder.png create mode 100644 docs/basics/terminology.md diff --git a/Makefile b/Makefile index 98b7045af..a4dddce9e 100644 --- a/Makefile +++ b/Makefile @@ -396,6 +396,7 @@ endif doc: $(PYTHON) tools/doxygen_symbol_gen.py doxygen + cp docs/basics/placeholder.png docs/html/placeholder.png clean: $(RM) -r $(BUILD_DIR) diff --git a/docs/basics/BUILD_WINDOWS.md b/docs/basics/BUILD_WINDOWS.md index ac2574646..67429d507 100644 --- a/docs/basics/BUILD_WINDOWS.md +++ b/docs/basics/BUILD_WINDOWS.md @@ -1,5 +1,4 @@ -@page build - +\page buildwindows Compiling for Windows ## Compiling mk64 Decomp In Windows ***This method is not recommended nor supported. However, it is the only solution to build in W7/W8. WSL is the path of least resistance, use that not this*** diff --git a/docs/basics/actors.md b/docs/basics/actors.md new file mode 100644 index 000000000..47a246e17 --- /dev/null +++ b/docs/basics/actors.md @@ -0,0 +1,2 @@ +\page actors How Actors Work +# Actors \ No newline at end of file diff --git a/docs/basics/actorsmenu.md b/docs/basics/actorsmenu.md new file mode 100644 index 000000000..0f0adef03 --- /dev/null +++ b/docs/basics/actorsmenu.md @@ -0,0 +1,77 @@ +\page actorsmenu Actors + +\htmlonly + +How actors in mk64 works. There are two kinds of actors. + + + +
+ +
+
+
+
Actors
+
+

Some actor stuff

+
+
+
+ +
+ +\endhtmlonly + +\subpage actors + diff --git a/docs/basics/Basic Concepts.md b/docs/basics/basicconcepts.md similarity index 86% rename from docs/basics/Basic Concepts.md rename to docs/basics/basicconcepts.md index b3b26019c..f187fd838 100644 --- a/docs/basics/Basic Concepts.md +++ b/docs/basics/basicconcepts.md @@ -1,10 +1,5 @@ -@page concepts -#### Definitions -* `Jump/Branch/Function` - Tells the cpu to execute instructions somewhere else and come back here when done. -* `Hexadecimal` - A [numbering system](https://en.wikipedia.org/wiki/Hexadecimal) just like decimal (also called base-ten) or roman numerals. An easy method for programmers and computers to understand each other which groups/separates bytes of information in a readable format. Representing information as decimal results in an unreadable mess. -* `s32/word/int` - A max size for a number. Data represented as 32 bits or 4 bytes: `0x00000001`. It consists of eight digits. -* `s16/half-word/short` - A number represented as 16 bits or 2 bytes: `0x0001`. It consists of four digits. Maximum value 65,535 (0xFFFF). -* `s8/byte/char` - A number represented as 8 bits or 1 byte: `0x01`. It consists of two digits. Maximum value 255 (0xFF). +@page concepts Basic Concepts +See terminology for explanations of terms. ## Addresses Computers use addresses to jump through code. This works similar to finding a house using its address. Except, that reaching the house is nearly instantaneous and it only contains more instructions and jumps or some data such as a texture or a text string. Also, when finished with the house, you travel back to the previous destination which may have some left-over instructions or more jumps. You can imagine this quickly becoming a spaghetti monster jumping all over the place. diff --git a/docs/basics/basicsmenu.md b/docs/basics/basicsmenu.md new file mode 100644 index 000000000..21c87c896 --- /dev/null +++ b/docs/basics/basicsmenu.md @@ -0,0 +1,125 @@ +\page basics Understanding the Basics + +\htmlonly + +Essential skills and concepts to help you get started with mk64 decomp. + + +
+ +
+
+
+
Installing mk64 Decomp
+
+

Steps for installing and building the game

+
+
+
+ +
+ +
+ +
+
+
+
test
+
+

test

+
+
+
+ +
+ + +

Foundational Knowledge

+

Become familiar with technical and low-level concepts.

+ +
+ +
+
+
+
Basic Concepts
+
+

Decomp, hexadecimal, cpu threads, addresses, and types to provide foundation knowledge.

+
+
+
+ +
+ +
+ +
+
+
+
Decomp Terminology
+
+

Common terms used in low-level computing and decomp.

+
+
+
+ +
+ +\endhtmlonly + +\subpage compiling +\subpage concepts +\subpage test +\subpage terminology +\subpage buildwindows \ No newline at end of file diff --git a/docs/basics/compiling.md b/docs/basics/compiling.md index e53b1905f..b03556168 100644 --- a/docs/basics/compiling.md +++ b/docs/basics/compiling.md @@ -1,54 +1,47 @@ -@page compiling Compiling mk64 -## Dependencies - +@page compiling Installing mk64 Decomp +## Build Instructions The build system has the following package requirements: binutils-mips >= 2.27 python3 >= 3.6 libaudiofile +* [Linux and WSL](#linux) +* [Arch](#arch) +* [Windows](#windows) +* [macOS](#macos) +* [Docker](#docker) + +### Compiling +* [US](#building-us) +* [EU](#building-eu) + + + To add submodules run `git submodule update --init --recursive` after cloning. -## EU Specific Steps (All versions) -Both EU builds first requires US to be built first: -``` -make -j -``` - -Now build either EU 1.0 `eu-1.0` or EU 1.1 `eu-final` -``` -make -j VERSION=eu-final -``` - -diff/first-diff commands -``` -python3 first-diff.py --eu -./diff -eu -``` - -#### Debian / Ubuntu +## Linux ``` sudo apt install build-essential pkg-config git binutils-mips-linux-gnu python3 zlib1g-dev libaudiofile-dev libcapstone-dev ``` -#### Arch Linux +### Arch -To install build dependencies: ``` sudo pacman -S base-devel capstone python ``` -Install the following AUR packages: +Install the following AUR package: * [mips64-elf-binutils](https://aur.archlinux.org/packages/mips64-elf-binutils) (AUR) -Review the n64decomp/sm64 readme for instructions to compile in other distributions. +Review the [n64decomp/sm64](https://github.com/n64decomp/sm64) readme for instructions to compile in other distributions. -#### Windows +## Windows -Compiling on Windows requires `MSYS2 MinGW x64`. The setup process is a tad intensive. +Not recommended. Use WSL unless this is your only option. [Instructions here](docs/BUILD_WINDOWS.md) -#### macOS +## macOS Install [Homebrew](https://brew.sh), then install the following dependencies: ``` @@ -56,9 +49,9 @@ brew update brew install python3 capstone coreutils make pkg-config tehzz/n64-dev/mips64-elf-binutils ``` -When building, use `gmake` to ensure that homebrew `make` is used instead of the old, macOS system `make`. +Build using `gmake` ensuring homebrew `make` is used instead of the old macOS system `make`. -#### Docker +## Docker Build the Docker image: ``` @@ -76,12 +69,35 @@ docker run --rm -v ${PWD}:/mk64 mk64 make -C tools docker run --rm -v ${PWD}:/mk64 mk64 make ``` -## Building +## Building US Place a US version of Mario Kart 64 called `baserom.us.z64` into the project folder for asset extraction. Run the following commands after pulling: ```bash make -C tools -make +make -j +``` + +## Building EU + +Building EU requires US to be built first. See above. + +mk64 decomp supports two EU versions +* EU 1.0 `eu-1.0` +* EU 1.1 `eu-final` + +Build using +``` +make -j VERSION=eu-1.0 +``` +or +``` +make -j VERSION=eu-final +``` + +First-diff/diff commands for EU +``` +python3 first-diff.py --eu +./diff -eu ``` \ No newline at end of file diff --git a/docs/basics/courses.md b/docs/basics/courses.md new file mode 100644 index 000000000..f3e9b250b --- /dev/null +++ b/docs/basics/courses.md @@ -0,0 +1,2 @@ +\page courses Courses +# Courses \ No newline at end of file diff --git a/docs/basics/coursesmenu.md b/docs/basics/coursesmenu.md new file mode 100644 index 000000000..031bc0c66 --- /dev/null +++ b/docs/basics/coursesmenu.md @@ -0,0 +1,77 @@ +\page coursesmenu Courses + +\htmlonly + +How courses work in mk64 + + + +
+ +
+
+
+
Courses
+
+

Some course related stuff

+
+
+
+ +
+ +\endhtmlonly + +\subpage courses + diff --git a/docs/basics/menu.html b/docs/basics/menu.html new file mode 100644 index 000000000..271f00e41 --- /dev/null +++ b/docs/basics/menu.html @@ -0,0 +1,68 @@ +Essential skills and concepts to help you get started with mk64 decomp. + + + + +
+
+
Compiling mk64
+

Instructions and dependencies required to build the game

+
+
+
+ + + +
+
+
Basic Concepts
+
+

Decomp, hexadecimal, cpu threads, addresses, and types to provide foundation knowledge. +

+
+
+ + + +
+
+
test
+

test

+
+
+
+ diff --git a/docs/basics/placeholder.png b/docs/basics/placeholder.png new file mode 100644 index 0000000000000000000000000000000000000000..4ad36b79201a78cd15f466f0d1e649f3ab731461 GIT binary patch literal 6761 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