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 000000000..4ad36b792 Binary files /dev/null and b/docs/basics/placeholder.png differ diff --git a/docs/basics/terminology.md b/docs/basics/terminology.md new file mode 100644 index 000000000..fca42f931 --- /dev/null +++ b/docs/basics/terminology.md @@ -0,0 +1,7 @@ +\page terminology Terminology +#### 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). \ No newline at end of file