diff options
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 126 |
1 files changed, 50 insertions, 76 deletions
diff --git a/INSTALL.md b/INSTALL.md index a76175862..6f5a2435d 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,116 +1,90 @@ -Follow the OS-specific instructions below. +# Prerequisites -# Linux +| Linux | macOS | Windows 10 (build 18917+) | Windows 10 (1709+) | Windows Vista, 7, 8, 8.1, and 10 (1507, 1511, 1607, and 1703) +| ----- | ----- | ------------------------- | ------------------ | --------------------------------------------------------- +| none | [Xcode Command Line Tools package][xcode] | [Windows Subsystem for Linux 2][wsl2] | [Windows Subsystem for Linux][wsl] | MSYS2 (see below) -Install [**devkitARM**](http://devkitpro.org/wiki/Getting_Started/devkitARM). +[xcode]: https://developer.apple.com/library/archive/technotes/tn2339/_index.html#//apple_ref/doc/uid/DTS40014588-CH1-DOWNLOADING_COMMAND_LINE_TOOLS_IS_NOT_AVAILABLE_IN_XCODE_FOR_MACOS_10_9__HOW_CAN_I_INSTALL_THEM_ON_MY_MACHINE_ +[wsl2]: https://docs.microsoft.com/windows/wsl/wsl2-install +[wsl]: https://docs.microsoft.com/windows/wsl/install-win10 -Make sure that there is an environment variable called DEVKITARM with the path of the directory before the "bin" directory containing "arm-none-eabi-as", "arm-none-eabi-cpp", "arm-none-eabi-ld" and "arm-none-eabi-objcopy". +The [prerelease version of the Linux subsystem](https://docs.microsoft.com/windows/wsl/install-legacy) available in the 1607 and 1703 releases of Windows 10 is obsolete so consider uninstalling it. -Then get the compiler from https://github.com/pret/agbcc and run the following commands. +Make sure that the `build-essential`, `git`, and `libpng-dev` packages are installed. The `build-essential` package includes the `make`, `gcc-core`, and `g++` packages so they do not have to be obtained separately. MSYS2 does not include `libpng-dev` so it must be built from source. -``` -./build.sh -./install.sh PATH_OF_POKEEMERALD_DIRECTORY -``` +Install the **devkitARM** toolchain of [devkitPro](https://devkitpro.org/wiki/Getting_Started) and add its environment variables. For Windows versions without the Linux subsystem, the devkitPro [graphical installer](https://github.com/devkitPro/installer/releases) includes a preconfigured MSYS2 environment, thus the steps below are not required. -Finally, build the rom. + export DEVKITPRO=/opt/devkitpro + echo "export DEVKITPRO=$DEVKITPRO" >> ~/.bashrc + export DEVKITARM=$DEVKITPRO/devkitARM + echo "export DEVKITARM=$DEVKITARM" >> ~/.bashrc -``` -make -``` -# Windows +# Installation -Install [**devkitARM**](http://devkitpro.org/wiki/Getting_Started/devkitARM). +To set up the repository: -Then get the compiled tools from https://github.com/pret/pokeruby-tools. Copy the `tools/` folder over the `tools/` folder in your pokeemerald directory. + git clone https://github.com/pret/pokeemerald + git clone https://github.com/pret/agbcc -You can then build pokeemerald using `make` in the MSYS environment provided with devkitARM. + cd ./agbcc + ./build.sh + ./install.sh ../pokeemerald -# Mac + cd ../pokeemerald -Installing pokeemerald on a Mac requires macOS >= 10.12 (Sierra or higher). +To build **pokeemerald.gba** and confirm it matches the official ROM image: -Download a [devkitPRO pacman](https://github.com/devkitPro/pacman/releases/tag/v1.0.0) + make compare -Run the following commands in Terminal: +## Notes +* If the base tools are not found on macOS in new Terminal sessions after the first successful build, run `echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> ~/.bash_profile` once to prevent the issue from occurring again. Verify that the `devkitarm-rules` package is installed as well; if not, install it by running `sudo dkp-pacman -S devkitarm-rules`. -``` -xcode-select --install +* If the repository was previously set up using Cygwin, delete the `.exe` files in the subfolders of the `tools` folder except for `agbcc` and try building again. [Learn the differences between MSYS2 and Cygwin.](https://github.com/msys2/msys2/wiki/How-does-MSYS2-differ-from-Cygwin) -sudo dkp-pacman -S devkitARM +# Guidance -export DEVKITPRO=/opt/devkitpro -echo "export DEVKITPRO=$DEVKITPRO" >> ~/.bashrc -export DEVKITARM=$DEVKITPRO/devkitARM -echo "export DEVKITARM=$DEVKITARM" >> ~/.bashrc -echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> ~/.bash_profile +To build **pokeemerald.gba** with your changes: -git clone https://github.com/pret/pokeemerald -git clone https://github.com/pret/agbcc + make -cd agbcc/ -./build.sh -./install.sh ../pokeemerald +## Parallel builds -cd ../pokeemerald -./build_tools.sh -``` +See [the GNU docs](https://www.gnu.org/software/make/manual/html_node/Parallel.html) and [this Stack Exchange thread](https://unix.stackexchange.com/questions/208568) for more information. -And build the ROM with `make`. +To speed up building, run: -If the step `./build.sh` in the above list of commands fails with the error `Makefile:1: /opt/devkitpro/devkitARM/base_tools: No such file or directory`, then try installing the pacman package `devkitarm-rules` by executing the command + make -j$(nproc) -``` -sudo dkp-pacman -S devkitarm-rules -``` +`nproc` is not available on macOS. The alternative is `sysctl -n hw.ncpu` ([relevant Stack Overflow thread](https://stackoverflow.com/questions/1715580)). -Executing `./build.sh` again should now succeed. +## Building without dependency scanning -# Faster builds +If only `.c` or `.s` files were changed, turn off the dependency scanning temporarily. Changes to any other files will be ignored and the build will either fail or not reflect those changes. -After the first build, subsequent builds are faster. You can further speed up the build: + make NODEP=1 -## Parallel build +## Building with devkitARM's C compiler -This significantly speeds up the build on modern machines. +This project supports the `arm-none-eabi-gcc` compiler included with devkitARM r52. To build this target, simply run: -By default `make` only runs a single thread. You can tell `make` to run on multiple threads with `make -j`. See the manfile for usage (`man make`). + make modern -The optimal value for `-j` is the number of logical cores on your machine. You can run `nproc` to see the exact number. +## Building with other toolchains -``` -$ nproc -8 -``` +To build using a toolchain other than devkitARM, override the `TOOLCHAIN` environment variable with the path to your toolchain, which must contain the subdirectory `bin`. -If you have 8 cores, run: `make -j8` + make TOOLCHAIN="/path/to/toolchain/here" -`-j` on its own will spawn a new thread for each job. A clean build will have thousands of jobs, which will be slower than not using -j at all. +The following is an example: -## Disable the dependency scanning + make TOOLCHAIN="/usr/local/arm-none-eabi" -If you've only changed `.c` or `.s` files, you can turn off the dependency scanning temporarily. Changes to any other files will be ignored, and the build will either fail or not reflect those changes. +To compile the `modern` target with this toolchain, the subdirectories `lib`, `include`, and `arm-none-eabi` must also be present. -`make NODEP=1` +## Building with debug info -# Building with devkitARM's C compiler +To build **pokeemerald.elf** with enhanced debug info, use the `DINFO` variable. -This project supports the `arm-none-eabi-gcc` compiler which ships with devkitARM r52. To build this target, simply run: - - make modern - -# Building with your own toolchain - -To build Pokemon Emerald with a toolchain other than devkitARM, override the `TOOLCHAIN` environment variable with the path to your toolchain. Example: - - make compare TOOLCHAIN=/usr/local/arm-none-eabi - -The path you pass to the `TOOLCHAIN` variable must contain the subdirectory `bin`. If you compile the `modern` target with this toolchain, the subdirectories `lib`, `include`, and `arm-none-eabi` must also be present. - -# Building with debug info - -To build the ELF file with enhanced debug info, use the `DINFO` variable: - - make compare DINFO=1 + make DINFO=1 |