diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000000..505fdeee91 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,8 @@ +.cache/ +.git/ +build/ +decompiler_out/ +failures/ +iso_data/ +out/ +log/ diff --git a/.zed/debug.json b/.zed/debug.json new file mode 100644 index 0000000000..87d5346b2f --- /dev/null +++ b/.zed/debug.json @@ -0,0 +1,62 @@ +// Project-local debug tasks +// +// For more documentation on how to configure debug tasks, +// see: https://zed.dev/docs/debugger +[ + { + "label": "Game - Jak 1 (Windows)", + "build": "Build - gk", + "program": "$ZED_WORKTREE_ROOT/out/build/Debug/bin/gk.exe", + "args": ["-v", "--game", "jak1", "--", "-fakeiso", "-debug"], + "request": "launch", + "adapter": "CodeLLDB", + }, + { + "label": "Game - Jak 2 (Windows)", + "build": "Build - gk", + "program": "$ZED_WORKTREE_ROOT/out/build/Debug/bin/gk.exe", + "args": ["-v", "--game", "jak2", "--", "-fakeiso", "-debug"], + "request": "launch", + "adapter": "CodeLLDB", + }, + { + "label": "Game - Jak 3 (Windows)", + "build": "Build - gk", + "program": "$ZED_WORKTREE_ROOT/out/build/Debug/bin/gk.exe", + "args": ["-v", "--game", "jak3", "--", "-fakeiso", "-debug"], + "request": "launch", + "adapter": "CodeLLDB", + }, + { + "label": "REPL - Jak 1 (Windows)", + "build": "Build - goalc", + "program": "$ZED_WORKTREE_ROOT/out/build/Debug/bin/goalc.exe", + "args": ["--user-auto", "--game", "jak1"], + "request": "launch", + "adapter": "CodeLLDB", + }, + { + "label": "REPL - Jak 2 (Windows)", + "build": "Build - goalc", + "program": "$ZED_WORKTREE_ROOT/out/build/Debug/bin/goalc.exe", + "args": ["--user-auto", "--game", "jak2"], + "request": "launch", + "adapter": "CodeLLDB", + }, + { + "label": "REPL - Jak 3 (Windows)", + "build": "Build - goalc", + "program": "$ZED_WORKTREE_ROOT/out/build/Debug/bin/goalc.exe", + "args": ["--user-auto", "--game", "jak3"], + "request": "launch", + "adapter": "CodeLLDB", + }, + { + "label": "Tests - Unit - Draft Only (Windows)", + "build": "Build - goalc-test", + "program": "$ZED_WORKTREE_ROOT/out/build/Debug/bin/goalc-test.exe", + "args": ["--gtest_brief=0", "--gtest_filter=\"*Draft*\""], + "request": "launch", + "adapter": "CodeLLDB", + }, +] diff --git a/.zed/tasks.json b/.zed/tasks.json new file mode 100644 index 0000000000..febf931992 --- /dev/null +++ b/.zed/tasks.json @@ -0,0 +1,111 @@ +// Project tasks configuration. See https://zed.dev/docs/tasks for documentation. +[ + { + "label": "Generate CMake - Release", + "command": "task gen-cmake-release", + }, + { + "label": "Generate CMake - Debug", + "command": "task gen-cmake-debug", + }, + { + "label": "Build Project - Release", + "command": "task build-release", + }, + { + "label": "Build Project - Debug", + "command": "task build-debug", + }, + { + "label": "Build - goalc", + "command": "task build-debug", + "env": { + "CMAKE_BUILD_ADDITIONAL_ARGS": "--target goalc", + }, + "cwd": "$ZED_WORKTREE_ROOT", + }, + { + "label": "Build - goalc-test", + "command": "task build-debug", + "env": { + "CMAKE_BUILD_ADDITIONAL_ARGS": "--target goalc-test", + }, + "cwd": "$ZED_WORKTREE_ROOT", + }, + { + "label": "Build - gk", + "command": "task build-debug", + "env": { + "CMAKE_BUILD_ADDITIONAL_ARGS": "--target gk", + }, + "cwd": "$ZED_WORKTREE_ROOT", + }, + { + "label": "Tests - Unit - Brief", + "command": "task unit-tests", + "env": { + "TEST_FILTER": "--gtest_brief=0", + }, + }, + { + "label": "Tests - Unit - Verbose", + "command": "task unit-tests", + "env": { + "TEST_FILTER": "--gtest_brief=1", + }, + }, + { + "label": "Tests - Unit - Type Consistency", + "command": "task unit-tests", + "env": { + "TEST_FILTER": "--gtest_brief=0 --gtest_filter=\"*TypeConsistency*\"", + }, + }, + { + "label": "Tests - Unit - WithGameTests", + "command": "task unit-tests", + "env": { + "TEST_FILTER": "--gtest_brief=0 --gtest_filter=\"*WithGameTests*\"", + }, + }, + { + "label": "Tests - Offline Tests", + "command": "task offline-tests-fast", + }, + { + "label": "Tests - Formatter", + "command": "task unit-tests", + "env": { + "TEST_FILTER": "--gtest_brief=0 --gtest_filter=\"*FormatterTests*\"", + }, + }, + { + "label": "Run - Game (Jak 1)", + "command": "task run-game", + "env": { + "GAME": "jak1", + }, + }, + { + "label": "Run - Game (Jak 2)", + "command": "task run-game", + "env": { + "GAME": "jak2", + }, + }, + { + "label": "Run - Game (Jak 3)", + "command": "task run-game", + "env": { + "GAME": "jak3", + }, + }, + { + "label": "Run - Decompiler", + "command": "task decomp", + }, + { + "label": "Format", + "command": "task format", + }, +] diff --git a/CMakePresets.json b/CMakePresets.json index 3cf4289e9f..9dd278d59b 100644 --- a/CMakePresets.json +++ b/CMakePresets.json @@ -225,6 +225,12 @@ "ZYDIS_BUILD_SHARED_LIB": "OFF" } }, + { + "name": "Debug-linux-clang", + "displayName": "Linux Release (clang)", + "description": "Build with Clang as Release with Debug Symbols", + "inherits": ["base-linux-debug", "base-clang"] + }, { "name": "Debug-linux-clang-static", "displayName": "Linux Static Release (clang)", diff --git a/LICENSE b/LICENSE index 5af9d46e37..9f8c67bbfb 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ ISC License -Copyright (c) 2020-2025 OpenGOAL Team +Copyright (c) 2020-2026 OpenGOAL Team Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above diff --git a/README.md b/README.md index 9087fba4d0..4dcd0c53e0 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ ## Please read first > [!IMPORTANT] -> Our repositories on GitHub are primarily for development of the project and tracking active issues. Most of the information you will find here pertains to setting up the project for development purposes and is not relevant to the end-user. +> Our repositories on GitHub are for development of the project and tracking active issues. Most of the information you will find here pertains to setting up the project for development purposes and is not relevant to the end-user. For a setup guide on how to install and play the game there is the following video that you can check out: https://youtu.be/K84UUMnkJc4 @@ -22,45 +22,27 @@ For questions or additional information pertaining to the project, we have a Dis Additionally, you can find further documentation and answers to **frequently asked questions** on the project's main website: https://opengoal.dev > [!WARNING] -> **Do not use this decompilation project without providing your own legally purchased copy of the game.** We do not distribute any assets from the game - you must use your own legitimately obtained PS2 copy of the game. We support every retail PAL, NTSC, and NTSC-J build, including Greatest Hits copies. +> **Do not use this decompilation project without the use of your own legally purchased copy of the game.** OpenGOAL does not include any assets from the original games, so you must provide your own legitimately obtained PS2 copy of the game. OpenGOAL supports every retail PAL, NTSC, and NTSC-J build, including Greatest Hits copies. Please note that does NOT include any of the later releases (PS3/PS4/PS5). - [Project Description](#project-description) - [Current Status](#current-status) - [Methodology](#methodology) - [Setting up a Development Environment](#setting-up-a-development-environment) - - [Docker](#docker) - - [Linux](#linux) - - [Ubuntu (20.04)](#ubuntu-2004) - - [Arch](#arch) - - [Fedora](#fedora) - - [Windows](#windows) - - [Required Software](#required-software) - - [Using Visual Studio](#using-visual-studio) - - [MacOS](#macos) - - [Intel Based](#intel-based) - - [Apple Silicon](#apple-silicon) - - [VSCode](#vscode) - - [Building and Debugging](#building-and-debugging) + - [OS Setup](#os-setup) + - [Editor Setup](#editor-setup) - [Building and Running the Game](#building-and-running-the-game) - [Extract Assets](#extract-assets) - - [Build the Game](#build-the-game) + - [Build the Game (Running the Compiler)](#build-the-game-running-the-compiler) - [Run the Game](#run-the-game) - [Connecting the REPL to the Game](#connecting-the-repl-to-the-game) - [Running the Game Without Auto-Booting](#running-the-game-without-auto-booting) - - [Interacting with the Game](#interacting-with-the-game) - [Technical Project Overview](#technical-project-overview) - - [`goalc`](#goalc) - - [Running the compiler](#running-the-compiler) - - [`decompiler`](#decompiler) - - [Running the decompiler](#running-the-decompiler) - - [`goal_src/`](#goal_src) - - [`game` runtime](#game-runtime) ## Project Description -This project is to port the original Jak and Daxter and Jak II to PC. Over 98% of the games are written in GOAL, a custom Lisp language developed by Naughty Dog. Our strategy is: +The project's goal is to port the original trilogy (Jak 1 -> Jak 3) to PC. Over 98% of the games were written in GOAL, a custom LISP language developed by Naughty Dog. Our strategy is: - decompile the original game code into human-readable GOAL code -- develop our own compiler for GOAL and recompile game code for x86-64 +- develop our own compiler for GOAL and recompile the game code for x86-64 - create a tool to extract game assets into formats that can be easily viewed or modified - create tools to repack game assets into a format that our port uses. @@ -70,219 +52,50 @@ Our objectives are: - try to match things from the original game and development as possible. For example, the original GOAL compiler supported live modification of code while the game is running, so we do the same, even though it's not required for just porting the game. - support modifications. It should be possible to make edits to the code without everything else breaking. -We support both Linux and Windows on x86-64. - -> We do not support, or plan to support the ARM architecture. This means that this will not run on devices such as a mobile device. +At the moment we support **x86_64** on Windows, Linux and macOS (via Rosetta translation). There are no plans to ever make a mobile release. ### Current Status -Jak 1 is largely playable from start to finish with a handful of bugs that are continually being ironed out. Jak 2 is in development. +- Jak 1 has been considered in a polished, complete state for years at this point. +- Jak 2 is considered in beta due to a few issues we are aware of that need fixing, however to the casual user, the game is essentially complete. +- Jak 3 has a good amount of work left to do. ![](./docs/img/promosmall1.png) ![](./docs/img/promosmall2.png) -YouTube playlist: +YouTube playlist showcasing some of the early progress for Jak 1: https://www.youtube.com/playlist?list=PLWx9T30aAT50cLnCTY1SAbt2TtWQzKfXX ### Methodology -To help with decompiling, we've built a decompiler that can process GOAL code and unpack game assets. We manually specify function types and locations where we believe the original code had type casts (or where they feel appropriate) until the decompiler succeeds, then we clean up the output of the decompiled code by adding comments and adjusting formatting, then save it in `goal_src`. +To assist with decompiling, we've built a decompiler that can process GOAL code and unpack game assets. We manually specify function types and locations where we believe the original code had type casts (or where they feel appropriate) until the decompilation succeeds, then we clean up the output of the decompiled code by adding comments and adjusting formatting, then save it in `goal_src/`. Our decompiler is designed specifically for processing the output of the original GOAL compiler. As a result, when given correct casts, it often produces code that can be directly fed into a compiler and works perfectly. This is continually tested as part of our unit tests. ## Setting up a Development Environment -The remainder of this README is catered towards people interested in building the project from source, typically with the intention on contributing as a developer. +The remainder of this README is aimed at people interested in building the project from source, typically with the intention of contributing as a developer. If this does not sound like you and you just want to play the game, refer to the above section [Quick Start](#quick-start) -### Docker +### OS Setup -All three Linux systems are supported using Docker. +- [Windows](/docs/setup/system/windows.md) +- [Linux](/docs/setup/system/linux.md) +- [MacOS](/docs/setup/system/macos.md) +- [Docker](/docs/setup/system/docker.md) -Pick your supported prefered flavour of linux and build your chosen image +### Editor Setup -``` -docker build -f docker/(Arch|Fedora|Ubuntu)/Dockerfile -t jak . -``` +You can of course use whatever editor you want, but here is some documentation that should help you get started on some of the editor's we have used and have written about: -This will create an image with all required dependencies and already built. - -``` -docker run -v "$(pwd)"/build:/home/jak/jak-project/build -it jak bash -``` - -Note: If you change the content of the `build/` directory you'll need to rerun the `build` command. Alternatively you can get the build via `docker cp`. - -This will link your `build/` folder to the images so can validate your build or test it on an external device. - -Docker images can be linked into your IDE (e.g. CLion) to help with codesniffing, static analysis, run tests and continuous build. - -Unfortunately you'll still need task runner on your local machine to run the game or instead, manually run the game via the commands found in `Taskfile.yml`. - -### Linux - -#### Ubuntu (20.04) - -Install packages and init repository: - -```sh -sudo apt install gcc make cmake ninja-build build-essential g++ nasm clang-format libxrandr-dev libxinerama-dev libxcursor-dev libpulse-dev libxi-dev python libgl1-mesa-dev libssl-dev -sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin -``` - -Compile: - -```sh -cmake -B build && cmake --build build -j 8 -``` - -Run tests: - -```sh -./test.sh -``` - -Note: we have found that `clang` and `lld` are significantly faster to compile and link than `gcc`, generate faster code, and have better warning messages. To install these: - -```sh -sudo apt install lld clang -``` - -and run `cmake` (in a fresh build directory) with: - -```sh -cmake -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .. -``` - -#### Arch - -Install packages and init repository: - -```sh -sudo pacman -S cmake libpulse base-devel nasm python libx11 libxrandr libxinerama libxcursor libxi -yay -S go-task -``` - -For Arch only, replace `task` with `go-task` in the rest of the instructions. - -Compile: - -```sh -cmake -B build && cmake --build build -j 8 -``` - -Run tests: - -```sh -./test.sh -``` - -#### Fedora - -Install packages and init repository: - -```sh -sudo dnf install cmake python lld clang nasm libX11-devel libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel pulseaudio-libs-devel mesa-libGL-devel -sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin -``` - -Compile with `clang`: - -```sh -cmake -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -B build -cmake --build build -j$(nproc) -``` - -Run tests: - -```sh -./test.sh -``` - -### Windows - -#### Required Software - -We primarily use Visual Studio on Windows for C++ development. Download the latest community edition from [here](https://visualstudio.microsoft.com/vs/). At the time of writing this is Visual Studio 2022. - -You will require the `Desktop development with C++` workload. This can be selected during the installation, or after via the `Visual Studio Installer`, modifying the Visual Studio Installation. - -On Windows, it's recommended to use a package manager, we use Scoop. Follow the steps on the bottom of the homepage [here](https://scoop.sh/) to get it. - -Once Scoop is installed, run the following commands: - -```sh -scoop install git llvm nasm python task -``` - -#### Using Visual Studio - -Clone the repository by running the following command in your folder of choice. - -```sh -git clone https://github.com/open-goal/jak-project.git -``` - -This will create a `jak-project` folder, open the project as a CMake project via Visual Studio. - -![](./docs/img/windows/open-project.png) - -Then build the entire project as `Windows Release (clang)`. You can also press Ctrl+Shift+B as a hotkey for Build All. We currently prefer `clang` on Windows as opposed to `msvc`, though it should work as well! - -![](./docs/img/windows/release-build.png) -![](./docs/img/windows/build-all.png) - -### MacOS - -> NOTE: Running the game requires an Apple Silicon Mac running macOS Sequoia, or an Intel Mac. - -Ensure that you have Xcode command line tools installed (this installs things like Apple Clang). If you don't, you can run the following command: - -```bash -xcode-select --install -``` - -On Apple Silicon, Rosetta 2 also must be installed: - -```bash -softwareupdate --install-rosetta -``` - -#### Building for x86_64 - -```bash -brew install cmake nasm ninja go-task clang-format -cmake -B build --preset=Release-macos-x86_64-clang -cmake --build build --parallel $((`sysctl -n hw.logicalcpu`)) -``` - -#### Building for ARM64 (experimental, unsupported) - -```bash -brew install cmake ninja go-task clang-format -cmake -B build --preset=Release-macos-arm64-clang -cmake --build build --parallel $((`sysctl -n hw.logicalcpu`)) -``` - -You may have to add the MacOS SDK to your `LIBRARY_PATH`: -- `export LIBRARY_PATH="$LIBRARY_PATH:/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib"` - -### VSCode - -If you either don't want to or cannot use Visual Studio for working with the C++ project, VSCode is a good alternatively. - -The `clangd` extension is [recommended](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) and requires `clangd` to be on your `$PATH`. If you can run `clangd` in a terminal successfully then you should be good to go. - -Once you generate your CMake for the first time the clangd LSP should be able to index the project and give you intellisense. - -#### Building and Debugging - -TODO - Consider Contributing Documentation :) +- [Visual Studio (Windows)](/docs/setup/dev/vs.md) +- [Visual Studio Code](/docs/setup/dev/vscode.md) +- [Zed](/docs/setup/dev/zed.md) ### Building and Running the Game -Getting a running game involves 4 steps: +Getting a running game involves 4 main steps: 1. Build C++ tools (follow Getting Started steps above for your platform) 2. Extract assets from the game @@ -291,25 +104,16 @@ Getting a running game involves 4 steps: #### Extract Assets -First, setup your settings so the following scripts know which game you are using, and which version. For the black label version of the game, run the following in a terminal: +First, we have to setup our environment so we know which game and version we are operating with. For the black label version of Jak 1 we would run the following: ```sh task set-game-jak1 -task set-decomp-ntscv1 -``` - -For other versions of the game, you will need to use a different `-set-decomp-` command. An example for the PAL version: - -```sh -task set-game-jak1 -task set-decomp-pal +task set-decomp-ntscv1 # or for example for PAL, `task set-decomp-pal` ``` > Run `task --list` to see the other available options -> At the time of writing, only Jak 1 is expected to work end-to-end! - -The first step is to extract your ISO file contents into the `iso_data/` folder. In the case of Jak 1 this is `iso_data/jak1`. +Next, ensure you extract your ISO file contents into the relevant `iso_data/` folder. In the case of Jak 1 this is `iso_data/jak1`. Once this is done, open a terminal in the `jak-project` folder and run the following: @@ -317,7 +121,7 @@ Once this is done, open a terminal in the `jak-project` folder and run the follo task extract ``` -#### Build the Game +#### Build the Game (Running the Compiler) The next step is to build the game itself. To do so, in the same terminal run the following: @@ -354,7 +158,7 @@ g > (mi) #### Run the Game -Finally the game can be ran. Open a second terminal from the `jak-project` directory and run the following: +Finally the game can be launched. Open a second terminal from the `jak-project` directory and run the following: ```sh task boot-game @@ -410,81 +214,6 @@ gc> (test-play) gc> ``` -#### Interacting with the Game - -In the graphics window, you can use the period key to bring up the debug menu. Controllers also work, using the same mapping as the original game. - -Check out the `pc_debug`, `examples` and `pc` folders under `goal_src` for some examples of GOAL code we wrote. The debug files that are not loaded automatically by the engine have instructions for how to run them. - ## Technical Project Overview -There are four main components to the project. - -1. `goalc` - the GOAL compiler for x86-64 -2. `decompiler` - our decompiler -3. `goal_src/` - the folder containing all OpenGOAL / GOOS code -4. `game` - aka the runtime written in C++ - -Let's break down each component. - -### `goalc` - -Our implementation of GOAL is called OpenGOAL. - -All of the compiler source code is in `goalc/`. The compiler is controlled through a prompt which can be used to enter commands to compile, connect to a running GOAL program for interaction, run the OpenGOAL debugger, or, if you are connected to a running GOAL program, can be used as a REPL to run code interactively. In addition to compiling code files, the compiler has features to pack and build data files. - -#### Running the compiler - -**Environment Agnostic** - -If you have installed `task` as recommended above, you can run the compiler with `task repl` - -**Linux** - -To run the compiler on Linux, there is a script `scripts/shell/gc.sh`. - -**Windows** - -On Windows, there is a `scripts/batch/gc.bat` scripts and a `scripts/batch/gc-no-lt.bat` script, the latter of which will not attempt to automatically attach to a running target. - -### `decompiler` - -The second component to the project is the decompiler. - -The decompiler will output code and other data intended to be inspected by humans in the `decompiler_out` folder. Files in this folder will not be used by the compiler. - -#### Running the decompiler - -You must have a copy of the PS2 game and place all files from the DVD inside a folder corresponding to the game within `iso_data` folder (`jak1` for Jak 1 Black Label, etc.), as seen in this picture: - -![](./docs/img/iso_data-help.png) - -The decompiler will extract assets to the `assets` folder. These assets will be used by the compiler when building the port, and you may want to turn asset extraction off after running it once. - -**Environment Agnostic** - -If you have installed `task` as recommended above, you can run the compiler with `task decomp` - -**Linux** - -To run, you can use `scripts/shell/decomp.sh` to run the decompiler - -**Windows** - -To run, you can use `scripts/shell/decomp-jak1.bat` to run the decompiler - -### `goal_src/` - -The game source code, written in OpenGOAL, is located in `goal_src`. All GOAL and GOOS code should be in this folder. - -### `game` runtime - -The final component is the "runtime", located in `game`. This is the part of the game that's written in C++. - -In the port, that includes: -- The "C Kernel", which contains the GOAL linker and some low-level GOAL language features. GOAL has a completely custom dynamically linked object file format so in order to load the first GOAL code, you need a linker written in C++. Some low-level functions for memory allocation, communicating with the I/O Processor, symbol table, strings, and the type system are also implemented in C, as these are required for the linker. It also listens for incoming messages from the compiler and passes them to the running game. This also initializes the game, by initializing the PS2 hardware, allocating the GOAL heaps, loading the GOAL kernel off of the DVD, and executing the kernel dispatcher function. This is in the `game/kernel` folder. This should be as close as possible to the game, and all differences should be noted with a comment. -- Implementation of Sony's standard library. GOAL code can call C library functions, and Naughty Dog used some Sony library functions to access files, memory cards, controllers, and communicate with the separate I/O Processor. The library functions are in `game/sce`. Implementations of library features specific to the PC port are located in `game/system`. -- The I/O Processor driver, OVERLORD. The PS2 had a separate CPU called the I/O Processor (IOP) that was directly connected to the DVD drive hardware and the sound hardware. Naughty Dog created a custom driver for the IOP that handled streaming data off of the DVD. It is much more complicated than I first expected. It's located in `game/overlord`. Like the C kernel, we try to keep this as close as possible to the actual game. -- Sound code. Naughty Dog used a third party library for sound called `989SND`. Code for the library and an interface for it is located in `game/sound`. -- PC specific graphics code. We have a functional OpenGL renderer and context that can create a game window and display graphics on it. The specific renderers used by the game however are mostly implemented. Aside from post-processing effects, everything in the game is rendered. This is located in `game/graphics`. While many liberties will be taken to make this work, the end result should very closely match the actual game. -- Extra assets used by the port in some fashion, located in `game/assets`. These include extra text files, icons, etc. +Some more detail about the various components of the project can be found [here](/docs/project-overview.md) diff --git a/Taskfile.yml b/Taskfile.yml index 6cb4d71d9b..7fe511f955 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -10,35 +10,35 @@ dotenv: tasks: # SETTINGS / CONFIGURATION settings: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --info' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --info" set-game-jak1: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --game jak1' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --game jak1" set-game-jak2: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --game jak2' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --game jak2" set-game-jak3: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --game jak3' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --game jak3" set-game-jakx: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --game jakx' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --game jakx" set-decomp-ntscv1: desc: "aka black label" cmds: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscv1' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscv1" set-decomp-ntscv2: desc: "aka red label" cmds: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscv2' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscv2" set-decomp-pal: desc: "PAL region version" cmds: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config pal' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config pal" set-decomp-ntscjp: desc: "NTSC-J region version" cmds: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscjp' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscjp" set-decomp-ntscko: desc: "NTSC-K region version" cmds: - - '{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscko' + - "{{.PYTHON}} ./scripts/tasks/update-env.py --decomp_config ntscko" # GENERAL extract: desc: "Extracts the game's assets from './iso_data' with the set decompiler config" @@ -46,7 +46,7 @@ tasks: - sh: test -f {{.DECOMP_BIN_RELEASE_DIR}}/decompiler{{.EXE_FILE_EXTENSION}} msg: "Couldn't locate decompiler executable in '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler'" cmds: - - "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler \"./decompiler/config/{{.DECOMP_CONFIG}}\" \"./iso_data\" \"./decompiler_out\" --version \"{{.DECOMP_CONFIG_VERSION}}\" --config-override '{\"decompile_code\": false, \"levels_extract\": true, \"allowed_objects\": []}'" + - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "allowed_objects": []}''' boot-game: desc: "Boots the game, it will fail if it's not already compiled!" preconditions: @@ -69,14 +69,35 @@ tasks: cmds: - "{{.GK_BIN_RELEASE_DIR}}/gk -v --game {{.GAME}} -- -fakeiso -debug" # DEVELOPMENT + clean-cmake: + desc: "Cleans up any existing cmake artifacts" + cmds: + - cmd: "{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path ./build" + - cmd: "{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path ./out/build" gen-cmake: desc: "Generate the CMake" cmds: - - "cmake -B build --preset={{.CMAKE_PRESET}}" + - "cmake {{.CMAKE_GEN_BUILD_DIR_DEBUG}} --preset={{.CMAKE_PRESET}}" + gen-cmake-release: + desc: "Generate the CMake" + cmds: + - "cmake {{.CMAKE_GEN_BUILD_DIR_RELEASE}} --preset={{.DEFAULT_CMAKE_RELEASE_PRESET}}" + gen-cmake-debug: + desc: "Generate the CMake" + cmds: + - "cmake {{.CMAKE_GEN_BUILD_DIR_DEBUG}} --preset={{.DEFAULT_CMAKE_DEBUG_PRESET}}" build: desc: "Build the project using the generated CMake" cmds: - - "cmake --build build --parallel {{.CMAKE_NUM_THREADS}}" + - "cmake {{.CMAKE_BUILD_DIR_DEBUG}} --parallel 8" + build-release: + desc: "Build the project using the generated CMake" + cmds: + - "cmake {{.CMAKE_BUILD_DIR_RELEASE}} --parallel 8" + build-debug: + desc: "Build the project using the generated CMake" + cmds: + - "cmake {{.CMAKE_BUILD_DIR_DEBUG}} --parallel 8 --target goalc" repl: desc: "Start the REPL" preconditions: @@ -93,9 +114,9 @@ tasks: format: desc: "Format code" cmds: - - cmd: '{{.PYTHON}} ./scripts/cpp/format-includes.py' - - cmd: '{{.PYTHON}} ./scripts/ci/lint-trailing-whitespace.py --fix' - - cmd: '{{.PYTHON}} ./third-party/run-clang-format/run-clang-format.py -r common decompiler game goalc test tools lsp -i' + - cmd: "{{.PYTHON}} ./scripts/cpp/format-includes.py" + - cmd: "{{.PYTHON}} ./scripts/ci/lint-trailing-whitespace.py --fix" + - cmd: "{{.PYTHON}} ./third-party/run-clang-format/run-clang-format.py -r common decompiler game goalc test tools lsp -i" - task: format-json format-gsrc: desc: "Run formatter on gsrc file" @@ -107,10 +128,10 @@ tasks: # DECOMPILING decomp: cmds: - - "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler \"./decompiler/config/{{.DECOMP_CONFIG}}\" \"./iso_data\" \"./decompiler_out\" --version \"{{.DECOMP_CONFIG_VERSION}}\" --config-override '{\"decompile_code\": true, \"levels_extract\": false}'" + - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": true, "levels_extract": false}''' decomp-file: cmds: - - "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler \"./decompiler/config/{{.DECOMP_CONFIG}}\" \"./iso_data\" \"./decompiler_out\" --version \"{{.DECOMP_CONFIG_VERSION}}\" --config-override '{\"decompile_code\": true, \"levels_extract\": false, \"allowed_objects\": [\"{{.FILE}}\"]}'" + - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": true, "levels_extract": false, "allowed_objects": ["{{.FILE}}"]}''' decomp-clean: cmds: - '{{.PYTHON}} ./scripts/tasks/clean-decomp.py --game "{{.GAME}}"' @@ -139,21 +160,21 @@ tasks: # ASSET RIPPING rip-textures: cmds: - - "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler \"./decompiler/config/{{.DECOMP_CONFIG}}\" \"./iso_data\" \"./decompiler_out\" --version \"{{.DECOMP_CONFIG_VERSION}}\" --config-override '{\"decompile_code\": false, \"levels_extract\": true, \"save_texture_pngs\": true}'" + - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "save_texture_pngs": true}''' rip-levels: cmds: - - "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler \"./decompiler/config/{{.DECOMP_CONFIG}}\" \"./iso_data\" \"./decompiler_out\" --version \"{{.DECOMP_CONFIG_VERSION}}\" --config-override '{\"decompile_code\": false, \"levels_extract\": true, \"rip_levels\": true}'" + - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "rip_levels": true}''' rip-collision: cmds: - - "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler \"./decompiler/config/{{.DECOMP_CONFIG}}\" \"./iso_data\" \"./decompiler_out\" --version \"{{.DECOMP_CONFIG_VERSION}}\" --config-override '{\"decompile_code\": false, \"levels_extract\": true, \"extract_collision\": true, \"rip_collision\": true}'" + - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "extract_collision": true, "rip_collision": true}''' rip-audio: cmds: - - "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler \"./decompiler/config/{{.DECOMP_CONFIG}}\" \"./iso_data\" \"./decompiler_out\" --version \"{{.DECOMP_CONFIG_VERSION}}\" --config-override '{\"decompile_code\": false, \"levels_extract\": true, \"rip_streamed_audio\": true}'" + - '{{.DECOMP_BIN_RELEASE_DIR}}/decompiler "./decompiler/config/{{.DECOMP_CONFIG}}" "./iso_data" "./decompiler_out" --version "{{.DECOMP_CONFIG_VERSION}}" --config-override ''{"decompile_code": false, "levels_extract": true, "rip_streamed_audio": true}''' # TOOLS analyze-ee-memory: cmds: - '{{.PYTHON}} ./scripts/tasks/extract-zip.py --file "{{.FILE}}" --out ./savestate_out/' - - '{{.MEMDUMP_BIN_RELEASE_DIR}}/memory_dump_tool ./savestate_out/eeMemory.bin --output-path ./ --game {{.GAME}} > ee-analysis.log' + - "{{.MEMDUMP_BIN_RELEASE_DIR}}/memory_dump_tool ./savestate_out/eeMemory.bin --output-path ./ --game {{.GAME}} > ee-analysis.log" watch-pcsx2: # {{.PYTHON}} -m pip install -U "watchdog[watchmedo]" cmds: @@ -163,7 +184,7 @@ tasks: type-search: desc: Just an example to show it running cmds: - - "{{.TYPESEARCH_BIN_RELEASE_DIR}}/type_searcher --output-path ./search-results.json --game {{.GAME}} --fields '[{\"type\":\"int16\",\"offset\":2},{\"type\":\"int16\",\"offset\":4}]'" + - '{{.TYPESEARCH_BIN_RELEASE_DIR}}/type_searcher --output-path ./search-results.json --game {{.GAME}} --fields ''[{"type":"int16","offset":2},{"type":"int16","offset":4}]''' update-treesitter: desc: Updates locally built tree-sitter rules cmds: @@ -173,11 +194,11 @@ tasks: fix-translations: desc: Finds and tries to fix invalid translation Characters cmds: - - '{{.PYTHON}} ./scripts/ci/lint-autoglottonyms.py --fix' - - '{{.PYTHON}} ./scripts/ci/lint-characters.py --fix' + - "{{.PYTHON}} ./scripts/ci/lint-autoglottonyms.py --fix" + - "{{.PYTHON}} ./scripts/ci/lint-characters.py --fix" lint: cmds: - - '{{.PYTHON}} ./scripts/ci/lint-trailing-whitespace.py' + - "{{.PYTHON}} ./scripts/ci/lint-trailing-whitespace.py" run-gpu-test: desc: "Runs the game's built in GPU test" preconditions: @@ -186,29 +207,32 @@ tasks: cmds: - "{{.GK_BIN_RELEASE_DIR}}/gk -v --gpu-test opengl --gpu-test-out-path ./gpu-test.json" # TESTS + unit-tests: + cmds: + - "{{.GOALCTEST_BIN_DEBUG_DIR}}/goalc-test{{.EXE_FILE_EXTENSION}} {{.TEST_FILTER}}" offline-tests: # ran by jenkins cmds: - - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --fail-on-cmp' + - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test{{.EXE_FILE_EXTENSION}} --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --fail-on-cmp' offline-test-file: cmds: - - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --file {{.FILE}}' + - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test{{.EXE_FILE_EXTENSION}} --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --file {{.FILE}}' offline-tests-fast: cmds: - - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --pretty-print --num_threads 32 --dump_current_output --fail-on-cmp' + - '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test{{.EXE_FILE_EXTENSION}} --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --pretty-print --num_threads 32 --dump_current_output --fail-on-cmp' # TODO - amalgamate offline-tests and this task, run twice if the previous step fails update-ref-tests: cmds: - - cmd: '{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path failures' + - cmd: "{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path failures" - cmd: '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test --iso_data_path "./iso_data/{{.GAME}}" --game {{.GAME}} --pretty-print --num_threads 32 --dump_current_output --fail-on-cmp' ignore_error: true - - '{{.PYTHON}} ./scripts/update_decomp_reference.py ./failures ./test/decompiler/reference/ --game {{.GAME}}' + - "{{.PYTHON}} ./scripts/update_decomp_reference.py ./failures ./test/decompiler/reference/ --game {{.GAME}}" - task: offline-tests-fast update-ref-file: cmds: - - cmd: '{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path failures' + - cmd: "{{.PYTHON}} ./scripts/tasks/delete-file-or-folder.py --path failures" - cmd: '{{.OFFLINETEST_BIN_RELEASE_DIR}}/offline-test --iso_data_path "./iso_data/{{.GAME}}" --file {{.FILE}} --game {{.GAME}} --dump_current_output --fail-on-cmp' ignore_error: true - - '{{.PYTHON}} ./scripts/update_decomp_reference.py ./failures ./test/decompiler/reference/ --game {{.GAME}}' + - "{{.PYTHON}} ./scripts/update_decomp_reference.py ./failures ./test/decompiler/reference/ --game {{.GAME}}" - task: offline-test-file type-test: cmds: diff --git a/docker/Arch/Dockerfile b/docker/Arch/Dockerfile deleted file mode 100644 index 1e82723e8b..0000000000 --- a/docker/Arch/Dockerfile +++ /dev/null @@ -1,28 +0,0 @@ -FROM archlinux:latest - -RUN pacman -Syyu --noconfirm --needed cmake libpulse base-devel nasm python git libx11 libxrandr libxinerama libxcursor libxi - -# makepkg user and workdir -ARG user=jak -RUN useradd --system --create-home $user \ - && echo "$user ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers.d/$user -USER $user -WORKDIR /home/$user - -# Install yay -RUN git clone https://aur.archlinux.org/yay.git \ - && cd yay \ - && makepkg -sri --needed --noconfirm \ - && cd \ - # Clean up - && rm -rf .cache yay - -RUN yay --noconfirm -S go-task - -RUN mkdir /home/$user/jak-project/ -COPY --chown=jak:jak . /home/$user/jak-project -RUN git config --global --add safe.directory /home/jak/jak-project - -WORKDIR /home/$user/jak-project - -RUN cmake -B build && cmake --build build -j 8 \ No newline at end of file diff --git a/docker/Fedora/Dockerfile b/docker/Fedora/Dockerfile deleted file mode 100644 index a150cf2fb0..0000000000 --- a/docker/Fedora/Dockerfile +++ /dev/null @@ -1,20 +0,0 @@ -FROM fedora:latest - -RUN dnf install -y curl cmake python lld clang nasm libX11-devel libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel pulseaudio-libs-devel -RUN sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin - -ARG user=jak - -RUN useradd -m -d /home/${user} ${user} - -USER $user - -WORKDIR /home/$user - -RUN mkdir /home/$user/jak-project/ -COPY --chown=jak:jak . /home/$user/jak-project - -WORKDIR /home/$user/jak-project - -RUN cmake -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -B build -RUN cmake --build build -j$(nproc) \ No newline at end of file diff --git a/docker/Ubuntu/Dockerfile b/docker/Ubuntu-20.04.Dockerfile similarity index 100% rename from docker/Ubuntu/Dockerfile rename to docker/Ubuntu-20.04.Dockerfile diff --git a/docs/img/code_progress.png b/docs/img/code_progress.png deleted file mode 100644 index 2d6032424c..0000000000 Binary files a/docs/img/code_progress.png and /dev/null differ diff --git a/docs/img/editors/zed/zed-build-proj.png b/docs/img/editors/zed/zed-build-proj.png new file mode 100644 index 0000000000..a724fd96ec Binary files /dev/null and b/docs/img/editors/zed/zed-build-proj.png differ diff --git a/docs/img/editors/zed/zed-debugger.png b/docs/img/editors/zed/zed-debugger.png new file mode 100644 index 0000000000..264d3b22af Binary files /dev/null and b/docs/img/editors/zed/zed-debugger.png differ diff --git a/docs/img/editors/zed/zed-gen-cmake.png b/docs/img/editors/zed/zed-gen-cmake.png new file mode 100644 index 0000000000..2f874d556e Binary files /dev/null and b/docs/img/editors/zed/zed-gen-cmake.png differ diff --git a/docs/img/editors/zed/zed-run-example.png b/docs/img/editors/zed/zed-run-example.png new file mode 100644 index 0000000000..efab647646 Binary files /dev/null and b/docs/img/editors/zed/zed-run-example.png differ diff --git a/docs/img/launcher-find-version.png b/docs/img/launcher-find-version.png deleted file mode 100644 index 0babc31b69..0000000000 Binary files a/docs/img/launcher-find-version.png and /dev/null differ diff --git a/docs/project-overview.md b/docs/project-overview.md new file mode 100644 index 0000000000..6f2ca7bfbd --- /dev/null +++ b/docs/project-overview.md @@ -0,0 +1,80 @@ +# Project Overview + +- [Project Overview](#project-overview) + - [`goalc`](#goalc) + - [Running the compiler](#running-the-compiler) + - [`decompiler`](#decompiler) + - [Running the decompiler](#running-the-decompiler) + - [`goal_src/`](#goal_src) + - [`game` runtime](#game-runtime) + +There are four main components to the project. + +1. `goalc` - the GOAL compiler for x86-64 +2. `decompiler` - our decompiler +3. `goal_src/` - the folder containing all OpenGOAL / GOOS code +4. `game` - aka the runtime written in C++ + +Let's break down each component. + +## `goalc` + +Our implementation of GOAL is called OpenGOAL. + +All of the compiler source code is in `goalc/`. The compiler is controlled through a prompt which can be used to enter commands to compile, connect to a running GOAL program for interaction, run the OpenGOAL debugger, or, if you are connected to a running GOAL program, can be used as a REPL to run code interactively. In addition to compiling code files, the compiler has features to pack and build data files. + +### Running the compiler + +**Environment Agnostic** + +If you have installed `task` as recommended above, you can run the compiler with `task repl` + +**Linux** + +To run the compiler on Linux, there is a script `scripts/shell/gc.sh`. + +**Windows** + +On Windows, there is a `scripts/batch/gc.bat` scripts and a `scripts/batch/gc-no-lt.bat` script, the latter of which will not attempt to automatically attach to a running target. + +## `decompiler` + +The second component to the project is the decompiler. + +The decompiler will output code and other data intended to be inspected by humans in the `decompiler_out` folder. Files in this folder will not be used by the compiler. + +### Running the decompiler + +You must have a copy of the PS2 game and place all files from the DVD inside a folder corresponding to the game within `iso_data` folder (`jak1` for Jak 1 Black Label, etc.), as seen in this picture: + +![](./docs/img/iso_data-help.png) + +The decompiler will extract assets to the `assets` folder. These assets will be used by the compiler when building the port, and you may want to turn asset extraction off after running it once. + +**Environment Agnostic** + +If you have installed `task` as recommended above, you can run the compiler with `task decomp` + +**Linux** + +To run, you can use `scripts/shell/decomp.sh` to run the decompiler + +**Windows** + +To run, you can use `scripts/shell/decomp-jak1.bat` to run the decompiler + +## `goal_src/` + +The game source code, written in OpenGOAL, is located in `goal_src`. All GOAL and GOOS code should be in this folder. + +## `game` runtime + +The final component is the "runtime", located in `game`. This is the part of the game that's written in C++. + +In the port, that includes: +- The "C Kernel", which contains the GOAL linker and some low-level GOAL language features. GOAL has a completely custom dynamically linked object file format so in order to load the first GOAL code, you need a linker written in C++. Some low-level functions for memory allocation, communicating with the I/O Processor, symbol table, strings, and the type system are also implemented in C, as these are required for the linker. It also listens for incoming messages from the compiler and passes them to the running game. This also initializes the game, by initializing the PS2 hardware, allocating the GOAL heaps, loading the GOAL kernel off of the DVD, and executing the kernel dispatcher function. This is in the `game/kernel` folder. This should be as close as possible to the game, and all differences should be noted with a comment. +- Implementation of Sony's standard library. GOAL code can call C library functions, and Naughty Dog used some Sony library functions to access files, memory cards, controllers, and communicate with the separate I/O Processor. The library functions are in `game/sce`. Implementations of library features specific to the PC port are located in `game/system`. +- The I/O Processor driver, OVERLORD. The PS2 had a separate CPU called the I/O Processor (IOP) that was directly connected to the DVD drive hardware and the sound hardware. Naughty Dog created a custom driver for the IOP that handled streaming data off of the DVD. It is much more complicated than I first expected. It's located in `game/overlord`. Like the C kernel, we try to keep this as close as possible to the actual game. +- Sound code. Naughty Dog used a third party library for sound called `989SND`. Code for the library and an interface for it is located in `game/sound`. +- PC specific graphics code. We have a functional OpenGL renderer and context that can create a game window and display graphics on it. The specific renderers used by the game however are mostly implemented. Aside from post-processing effects, everything in the game is rendered. This is located in `game/graphics`. While many liberties will be taken to make this work, the end result should very closely match the actual game. +- Extra assets used by the port in some fashion, located in `game/assets`. These include extra text files, icons, etc. diff --git a/docs/setup/dev/vs.md b/docs/setup/dev/vs.md new file mode 100644 index 0000000000..8e107eea8d --- /dev/null +++ b/docs/setup/dev/vs.md @@ -0,0 +1,18 @@ +# Visual Studio + +## Known Issues + +- Later versions of 2022 have issues with intellisense when using clang +- Recent versions of 2026 have issues with CMake where the project will endlessly build: + - https://developercommunity.visualstudio.com/t/Switching-git-branches-seemingly-causes-/11025316?viewtype=all + +## Steps + +This will create a `jak-project` folder, open the project as a CMake project via Visual Studio. + +![](/docs/img/windows/open-project.png) + +Then build the entire project as `Windows Release (clang)`. You can also press Ctrl+Shift+B as a hotkey for Build All. We currently prefer `clang` on Windows as opposed to `msvc`, though it should work as well! + +![](/docs/img/windows/release-build.png) +![](/docs/img/windows/build-all.png) diff --git a/docs/setup/dev/vscode.md b/docs/setup/dev/vscode.md new file mode 100644 index 0000000000..bc0086b24c --- /dev/null +++ b/docs/setup/dev/vscode.md @@ -0,0 +1,11 @@ +# VSCode + +If you either don't want to or cannot use Visual Studio for working with the C++ project, VSCode is a good alternative. + +The `clangd` extension is [recommended](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) and requires `clangd` to be on your `$PATH`. If you can run `clangd` in a terminal successfully then you should be good to go. + +Once you generate your CMake for the first time the clangd LSP should be able to index the project and give you intellisense. + +## Building and Debugging + +TODO - Consider Contributing Documentation :) diff --git a/docs/setup/dev/zed.md b/docs/setup/dev/zed.md new file mode 100644 index 0000000000..36074ad4b9 --- /dev/null +++ b/docs/setup/dev/zed.md @@ -0,0 +1,25 @@ +# Zed + +Zed comes with out of the box C++ support via `clangd`. The project comes with a bunch of already setup task and debug configurations. Note that many of them depend on the usage of `task` to make them cross-OS compatible (Zed at this time doesn't allow for OS-conditional logic within the task definitions). + +## Recommended Extensions: + +- NeoCMake + +## Building the Project + +We are going to build a debug version of the project because that is most useful for development. + +Run the `task: spawn` command (default shortcut is `Alt-Shift-T`) and run `Generate CMake: Debug` + +![](/docs/img/editors/zed/zed-gen-cmake.png) + +Then do the same thing to run `Build Project: Debug` + +![](/docs/img/editors/zed/zed-build-proj.png) + +The project is now fully built, you can now for example -- launch the REPL (`goalc`), or the game (`gk`) and attach breakpoints. + +![](/docs/img/editors/zed/zed-run-example.png) + +![](/docs/img/editors/zed/zed-debugger.png) diff --git a/docs/setup/system/docker.md b/docs/setup/system/docker.md new file mode 100644 index 0000000000..3ed29d83a4 --- /dev/null +++ b/docs/setup/system/docker.md @@ -0,0 +1,21 @@ +# Docker + +You can use docker to compile the project as well. Note that the Dockerfiles in the project often fall out of maitenance because no one on the main development team uses them, when this is noticed, they are deleted. + +```sh +docker build -f docker/Ubuntu-20.04.Dockerfile -t jak . +``` + +This will create an image with all required dependencies and already built. + +```sh +docker run -v "$(pwd)"/build:/home/jak/jak-project/build -it jak bash +``` + +Note: If you change the content of the `build/` directory you'll need to rerun the `docker build` command. Alternatively you can get the build via `docker cp`. + +This will link your `build/` folder to the images so can validate your build or test it on an external device. + +Docker images can be linked into your IDE (e.g. CLion) to help with codesniffing, static analysis, run tests and continuous build. + +Unfortunately you'll still need task runner on your local machine to run the game or instead, manually run the game via the commands found in `Taskfile.yml`. diff --git a/docs/setup/system/linux.md b/docs/setup/system/linux.md new file mode 100644 index 0000000000..ffc6cf16bd --- /dev/null +++ b/docs/setup/system/linux.md @@ -0,0 +1,60 @@ +# Linux Environment Setup + +- [Linux Environment Setup](#linux-environment-setup) + - [Packages](#packages) + - [Ubuntu (20.04)](#ubuntu-2004) + - [Arch](#arch) + - [Fedora](#fedora) + - [Compiling and Building](#compiling-and-building) + + +## Packages + +### Ubuntu (20.04) + +```sh +sudo apt install gcc make cmake ninja-build build-essential g++ nasm clang-format libxrandr-dev libxinerama-dev libxcursor-dev libpulse-dev libxi-dev python libgl1-mesa-dev libssl-dev +sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin +``` + +## Arch + +```sh +sudo pacman -S cmake libpulse base-devel nasm python libx11 libxrandr libxinerama libxcursor libxi +yay -S go-task +``` + +> Note: Any later documentation that shows a `task ...` command, would instead be a `go-task ...` command. + +## Fedora + +```sh +sudo dnf install cmake python lld clang nasm libX11-devel libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel pulseaudio-libs-devel mesa-libGL-devel +sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin +``` + +## Compiling and Building + +Compile: + +```sh +cmake -B build && cmake --build build -j 8 +``` + +Run tests: + +```sh +./test.sh +``` + +Note: we have found that `clang` and `lld` are significantly faster to compile and link than `gcc`, generate faster code, and have better warning messages. To install these: + +```sh +sudo apt install lld clang +``` + +and run `cmake` (in a fresh build directory) with: + +```sh +cmake -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .. +``` diff --git a/docs/setup/system/macos.md b/docs/setup/system/macos.md new file mode 100644 index 0000000000..de3205e5de --- /dev/null +++ b/docs/setup/system/macos.md @@ -0,0 +1,34 @@ +# MacOS Environment Setup + +Running the game requires an Apple Silicon Mac running macOS Sequoia, or an Intel Mac. Additionally, we currently build on macOS 15 (Sequoia) at this time. + +Ensure that you have Xcode command line tools installed (this installs things like Apple Clang). If you don't, you can run the following command: + +```bash +xcode-select --install +``` + +On Apple Silicon, Rosetta 2 also must be installed: + +```bash +softwareupdate --install-rosetta +``` + +## Building for x86_64 + +```bash +brew install cmake nasm ninja go-task clang-format +cmake -B build --preset=Release-macos-x86_64-clang +cmake --build build --parallel $((`sysctl -n hw.logicalcpu`)) +``` + +## Building for ARM64 (experimental, unsupported) + +```bash +brew install cmake ninja go-task clang-format +cmake -B build --preset=Release-macos-arm64-clang +cmake --build build --parallel $((`sysctl -n hw.logicalcpu`)) +``` + +You may have to add the MacOS SDK to your `LIBRARY_PATH`: +- `export LIBRARY_PATH="$LIBRARY_PATH:/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib"` diff --git a/docs/setup/system/windows.md b/docs/setup/system/windows.md new file mode 100644 index 0000000000..cc8f403bbc --- /dev/null +++ b/docs/setup/system/windows.md @@ -0,0 +1,13 @@ +# Windows Environment Setup + +Even if you do not intend to use Visual Studio as your IDE of choice, it is the only officially supported way of downloading the various Windows SDKs to build the C++ project. + +Download the latest community edition from [here](https://visualstudio.microsoft.com/vs/). At the time of writing this is Visual Studio 2022. + +You will require the `Desktop development with C++` workload. This can be selected during the installation, or after via the `Visual Studio Installer` program and modifying the Visual Studio Installation. + +We recommend getting the rest of the project's dependencies via a package manager, and for that we use Scoop. Follow the steps on the bottom of the homepage [here](https://scoop.sh/) to get it installed. + +```sh +scoop install git llvm nasm python task ninja cmake +``` diff --git a/scripts/tasks/Taskfile_darwin.yml b/scripts/tasks/Taskfile_darwin.yml index 4982077bf9..8b9692d564 100644 --- a/scripts/tasks/Taskfile_darwin.yml +++ b/scripts/tasks/Taskfile_darwin.yml @@ -1,13 +1,20 @@ version: 3 vars: - GOALC_BIN_RELEASE_DIR: './build/goalc' - GK_BIN_RELEASE_DIR: './build/game' - DECOMP_BIN_RELEASE_DIR: './build/decompiler' - MEMDUMP_BIN_RELEASE_DIR: './build/tools' - TYPESEARCH_BIN_RELEASE_DIR: './build/tools' - OFFLINETEST_BIN_RELEASE_DIR: './build' - GOALCTEST_BIN_RELEASE_DIR: './build' - FORMATTER_BIN_RELEASE_DIR: './build/tools' - EXE_FILE_EXTENSION: '' - PYTHON: 'python3' + GOALC_BIN_RELEASE_DIR: "./build/goalc" + GK_BIN_RELEASE_DIR: "./build/game" + DECOMP_BIN_DEBUG_DIR: "./build/decompiler" + DECOMP_BIN_RELEASE_DIR: "./build/decompiler" + MEMDUMP_BIN_RELEASE_DIR: "./build/tools" + TYPESEARCH_BIN_RELEASE_DIR: "./build/tools" + OFFLINETEST_BIN_RELEASE_DIR: "./build" + GOALCTEST_BIN_RELEASE_DIR: "./build" + FORMATTER_BIN_RELEASE_DIR: "./build/tools" + EXE_FILE_EXTENSION: "" + PYTHON: "python3" + DEFAULT_CMAKE_RELEASE_PRESET: "Release-macos-arm64-clang" + DEFAULT_CMAKE_DEBUG_PRESET: "" + CMAKE_GEN_BUILD_DIR_RELEASE: "-B build" + CMAKE_GEN_BUILD_DIR_DEBUG: "-B build" + CMAKE_BUILD_DIR_RELEASE: "--build build" + CMAKE_BUILD_DIR_DEBUG: "--build build" diff --git a/scripts/tasks/Taskfile_linux.yml b/scripts/tasks/Taskfile_linux.yml index 4982077bf9..0453bbb734 100644 --- a/scripts/tasks/Taskfile_linux.yml +++ b/scripts/tasks/Taskfile_linux.yml @@ -1,13 +1,20 @@ version: 3 vars: - GOALC_BIN_RELEASE_DIR: './build/goalc' - GK_BIN_RELEASE_DIR: './build/game' - DECOMP_BIN_RELEASE_DIR: './build/decompiler' - MEMDUMP_BIN_RELEASE_DIR: './build/tools' - TYPESEARCH_BIN_RELEASE_DIR: './build/tools' - OFFLINETEST_BIN_RELEASE_DIR: './build' - GOALCTEST_BIN_RELEASE_DIR: './build' - FORMATTER_BIN_RELEASE_DIR: './build/tools' - EXE_FILE_EXTENSION: '' - PYTHON: 'python3' + GOALC_BIN_RELEASE_DIR: "./build/goalc" + GK_BIN_RELEASE_DIR: "./build/game" + DECOMP_BIN_DEBUG_DIR: "./build/decompiler" + DECOMP_BIN_RELEASE_DIR: "./build/decompiler" + MEMDUMP_BIN_RELEASE_DIR: "./build/tools" + TYPESEARCH_BIN_RELEASE_DIR: "./build/tools" + OFFLINETEST_BIN_RELEASE_DIR: "./build" + GOALCTEST_BIN_RELEASE_DIR: "./build" + FORMATTER_BIN_RELEASE_DIR: "./build/tools" + EXE_FILE_EXTENSION: "" + PYTHON: "python3" + DEFAULT_CMAKE_RELEASE_PRESET: "Release-linux-clang" + DEFAULT_CMAKE_DEBUG_PRESET: "Debug-linux-clang" + CMAKE_GEN_BUILD_DIR_RELEASE: "-B build" + CMAKE_GEN_BUILD_DIR_DEBUG: "-B build" + CMAKE_BUILD_DIR_RELEASE: "--build build" + CMAKE_BUILD_DIR_DEBUG: "--build build" diff --git a/scripts/tasks/Taskfile_windows.yml b/scripts/tasks/Taskfile_windows.yml index 2aa17c3d77..7fba43689a 100644 --- a/scripts/tasks/Taskfile_windows.yml +++ b/scripts/tasks/Taskfile_windows.yml @@ -1,13 +1,21 @@ version: 3 vars: - GOALC_BIN_RELEASE_DIR: './out/build/Release/bin' - GK_BIN_RELEASE_DIR: './out/build/Release/bin' - DECOMP_BIN_RELEASE_DIR: './out/build/Release/bin' - MEMDUMP_BIN_RELEASE_DIR: './out/build/Release/bin' - TYPESEARCH_BIN_RELEASE_DIR: './out/build/Release/bin' - OFFLINETEST_BIN_RELEASE_DIR: './out/build/Release/bin' - GOALCTEST_BIN_RELEASE_DIR: './out/build/Release/bin' - FORMATTER_BIN_RELEASE_DIR: './out/build/Release/bin' - EXE_FILE_EXTENSION: '.exe' - PYTHON: 'python' + GOALC_BIN_RELEASE_DIR: "./out/build/Release/bin" + GK_BIN_RELEASE_DIR: "./out/build/Release/bin" + DECOMP_BIN_DEBUG_DIR: "./out/build/Debug/bin" + DECOMP_BIN_RELEASE_DIR: "./out/build/Release/bin" + MEMDUMP_BIN_RELEASE_DIR: "./out/build/Release/bin" + TYPESEARCH_BIN_RELEASE_DIR: "./out/build/Release/bin" + OFFLINETEST_BIN_RELEASE_DIR: "./out/build/Release/bin" + GOALCTEST_BIN_RELEASE_DIR: "./out/build/Release/bin" + GOALCTEST_BIN_DEBUG_DIR: "./out/build/Debug/bin" + FORMATTER_BIN_RELEASE_DIR: "./out/build/Release/bin" + EXE_FILE_EXTENSION: ".exe" + PYTHON: "python" + DEFAULT_CMAKE_RELEASE_PRESET: "Release-windows-clang" + DEFAULT_CMAKE_DEBUG_PRESET: "Debug-windows-clang" + CMAKE_GEN_BUILD_DIR_RELEASE: "" + CMAKE_GEN_BUILD_DIR_DEBUG: "" + CMAKE_BUILD_DIR_RELEASE: "--build ./out/build/Release" + CMAKE_BUILD_DIR_DEBUG: "--build ./out/build/Debug" diff --git a/test_no_filter.sh b/test_no_filter.sh index 03e27f4150..e6e06387d6 100755 --- a/test_no_filter.sh +++ b/test_no_filter.sh @@ -3,4 +3,4 @@ # Directory of this script DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" - $DIR/build/goalc-test --gtest_color=yes "$@" +$DIR/build/goalc-test --gtest_color=yes "$@" diff --git a/third-party/zydis/resources/VersionInfo.rc b/third-party/zydis/resources/VersionInfo.rc index 4af550459c..bbe9a82d3a 100644 --- a/third-party/zydis/resources/VersionInfo.rc +++ b/third-party/zydis/resources/VersionInfo.rc @@ -47,7 +47,7 @@ BEGIN VALUE "FileDescription", "Zyan Disassembler Library" VALUE "FileVersion", "5.0.0.0" VALUE "InternalName", "Zydis" - VALUE "LegalCopyright", "Copyright \xA9 2014-2024 by zyantific.com" + VALUE "LegalCopyright", "Copyright 2014-2024 by zyantific.com" VALUE "OriginalFilename", "Zydis.dll" VALUE "ProductName", "Zyan Disassembler Library" VALUE "ProductVersion", "5.0.0.0"