Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update building/running instructions for macOS #1609

Open
wants to merge 1 commit into
base: gh-pages
Choose a base branch
from
Open

Update building/running instructions for macOS #1609

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 47 additions & 9 deletions building.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ <h1>Plasma</h1>

<h2>Building</h2>

<p>Currently, the complete game client can only be built for Windows, using Visual Studio.</p>
<p>By default these steps will compile a client targeting your machine architecture. It is possible to build a 64-bit game client, but only the 32-bit (x86) client is officially supported.</p>
<p>Currently, the complete game client can only be built for Windows (using Visual Studio) and macOS (using Xcode). Several tools can be built for Linux, but not a complete game client.</p>
<p>By default these steps will compile a client targeting your machine architecture. It is possible to build a 64-bit game client, but only the 32-bit (x86) Windows client is officially supported.</p>


<h3 id="dependencies">Library Dependencies</h3>
Expand Down Expand Up @@ -151,11 +151,49 @@ <h3 id="building-windows">Building on Windows</h3>
</ol>


<h3 id="building-nix">Building on macOS &amp; Linux</h3>
<h3 id="building-mac">Building on macOS</h3>

<p>Linux and macOS are <strong>not officially supported targets</strong>, and the game client does not compile. However, several of the tools can be built and run.</p>
<p>Compiling on macOS requires macOS version 10.14 or newer, and the Xcode build system. Xcode is available as a free download from the <a href="https://apps.apple.com/us/app/xcode/id497799835?mt=12/">App Store</a>.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<p>Compiling on macOS requires macOS version 10.14 or newer, and the Xcode build system. Xcode is available as a free download from the <a href="https://apps.apple.com/us/app/xcode/id497799835?mt=12/">App Store</a>.</p>
<p>Compiling on macOS requires macOS version 10.14 or newer and the Xcode build system. Xcode is available as a free download from the <a href="https://apps.apple.com/us/app/xcode/id497799835?mt=12/">App Store</a>.</p>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Compiling requires Xcode 12.2. In turn - Xcode 12.2 requires macOS 10.15.4.

The resulting output will run on 10.14 - but it would be inaccurate to say you can compile from 10.14.

If we made MSL 2.3 an optional part of the build - we could get this lower. But for now Xcode 12.2 and the macOS 11 SDK are required.


<p>You will need to ensure all the required dependencies are available. On macOS, a Homebrew bundle file is included in the repository, which can be installed by running <code>brew bundle</code>. You can also use vcpkg on these platforms for automatically managing dependencies.</p>
<p>We strongly encourage using vcpkg to automatically build dependencies, however this requires some tools be manually installed in advance. The required tools are CMake, nasm, and pkg-config, and can be installed using common package managers such as Homebrew or MacPorts.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<p>We strongly encourage using vcpkg to automatically build dependencies, however this requires some tools be manually installed in advance. The required tools are CMake, nasm, and pkg-config, and can be installed using common package managers such as Homebrew or MacPorts.</p>
<p>We strongly encourage using vcpkg to automatically build dependencies; however, this requires some tools be manually installed in advance. The required tools are CMake, nasm, and pkg-config, and can be installed using common package managers such as Homebrew or MacPorts.</p>


<p>For Homebrew users who wish to manage all dependencies, a Homebrew bundle file is included in the repository, which can be installed by running <code>brew bundle</code> after cloning the project.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the strongly recommend above covers things - but I'm not sure one could build a real release on Homebrew. I'm not sure whats included are universal binaries - and bundling Python as anything other than the static lib we get from vcpkg is not at all working. So the resulting output is really only going to be usable from the Mac it was built on.


<ol>
<li>
<p>Clone the repository from GitHub, including all submodules, using a git client. On the command line, this can be done by executing the following:<br>
<code>git clone --recurse-submodules https://github.com/H-uru/Plasma.git</code></p>
</li>

<li>
<p>In the folder where you cloned the repository, run CMake to create a build folder:<br>
<code>cmake -G Xcode -DUSE_VCPKG=ON -B build -S .</code></p>
<p>This assumes you wish to use vcpkg to build dependencies. Leave off the <tt>USE_VCPKG</tt> flag to manage dependencies yourself.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<p>This assumes you wish to use vcpkg to build dependencies. Leave off the <tt>USE_VCPKG</tt> flag to manage dependencies yourself.</p>
<p>This assumes you wish to use vcpkg to build dependencies. Remove <tt>-DUSEVCPKG=ON</tt> to manage dependencies yourself.</p>

</li>

<li>
<p>Compile the project with the following command:<br>
<code>cmake -B build --config RelWithDebInfo</code></p>
</li>

<li>
<p>Install the resulting tools with the following command:<br>
<code>cmake -B build --target install --config RelWithDebInfo</code></p>
</li>

<li>
<p>The client will be built and installed into the <tt>build/install/client</tt> subfolder of where you cloned the repo.</p>
<p>The client output folder will be referred to as your “MOUL-OS” folder in the instructions on <a href="running.html">Running Plasma</a>.</p>
</li>
</ol>

<p>You can also open the project in the Xcode IDE by opening the <tt>build/Plasma.xcodeproj</tt> file.</p>

<h3 id="building-nix">Building on Linux</h3>

<p>Linux and other UNIX-like operating systems are <strong>not officially supported targets</strong>, and the game client does not compile. However, several of the tools can be built and run.</p>

<p>You will need to ensure all the required dependencies are available. You can also use vcpkg on these platforms for automatically managing dependencies.</p>

<ol>
<li>
Expand All @@ -165,19 +203,19 @@ <h3 id="building-nix">Building on macOS &amp; Linux</h3>

<li>
<p>In the folder where you cloned the repository, run CMake to create a build folder:<br>
<code>cmake --builddir build -S .</code></p>
<code>cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -B build -S .</code></p>
<p>If you want to use vcpkg to automatically build dependencies, enable the <tt>USE_VCPKG</tt> option:<br>
<code>cmake -D USE_VCPKG=ON --builddir build -S .</code></p>
<code>cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DUSE_VCPKG=ON -B build -S .</code></p>
</li>

<li>
<p>Compile the project with the following command:<br>
<code>cmake --builddir build --config RelWithDebInfo</code></p>
<code>cmake -B build</code></p>
</li>

<li>
<p>Install the resulting tools with the following command:<br>
<code>cmake --install build --config RelWithDebInfo</code></p>
<code>cmake -B build --target install</code></p>
</li>

<li>
Expand Down
28 changes: 16 additions & 12 deletions running.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,17 @@ <h2>Running</h2>
<p>You should <strong>never</strong> use a custom-built client with servers that are not explicitly intended for testing. Newer features in the client code might be incompatible with those servers and could break the game for other players or result in permanent player data corruption.</p>
</div>


<h3 id="running-windows">Running on Windows</h3>
<p>Before running the client, you will need to do the following:</p>

<ol>
<li><p>Copy the folders <tt>avi</tt>, <tt>dat</tt>, and <tt>sfx</tt> from your existing MOULa installation to the MOUL-OS folder.</p></li>

<li><p>Get the appropriate <tt>server.ini</tt> file for the server you will be connecting to.</p></li>
</ol>

<h3 id="running-windows">Running on Windows</h3>

<ol start="3">
<li><p>Create a shortcut in the MOUL-OS folder to the compiled <tt>plClient.exe</tt>.</p></li>

<li><p>Edit the shortcut’s properties, and after the final quotation mark in the Target field, add <code>/LocalData</code>.<br>Also, change the Start in field to the path of your MOUL-OS folder.</p></li>
Expand All @@ -55,11 +58,7 @@ <h3 id="running-vs">Running in Visual Studio (for debugging)</h3>

<p>Follow these instructions if you wish to be able to debug using a single content folder from inside Visual Studio.</p>

<ol>
<li><p>Copy the folders <tt>avi</tt>, <tt>dat</tt>, and <tt>sfx</tt> from your existing MOULa installation to the MOUL-OS folder.</p></li>

<li><p>Get the appropriate <tt>server.ini</tt> file for the server you will be connecting to.</p></li>

<ol start="3">
<li><p>Open the Plasma folder in Visual Studio.</p></li>

<li><p>Switch to CMake Targets View in the Solution Explorer.</p></li>
Expand All @@ -72,14 +71,19 @@ <h3 id="running-vs">Running in Visual Studio (for debugging)</h3>
</ol>


<!-- No Linux client available, no point including this right now
<h3 id="running-linux">Running on Linux</h3>
<h3 id="running-mac">Running on macOS</h3>

<ol>
<li><p>Copy the folders <tt>avi</tt>, <tt>dat</tt>, and <tt>sfx</tt> from your existing MOULa installation to the MOUL-OS folder.</p></li>
<ol start="3">
<li><p>Open a terminal window in your MOUL-OS folder.</p></li>

<li><p>Get the appropriate <tt>server.ini</tt> file for the server you will be connecting to.</p></li>
<li><p>Run <code>./plClient.app/Contents/MacOS/plClient --LocalData</code> to start the client.</p></li>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@colincornaby Is this the best option, or does something like open plClient.app --LocalData work?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On my mini, I've been using open -n ./plClient.app --args -LocalData.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've been using NoSelfPatch so that I download all the game data without looking for a client patch.

(Curious if that's the intended behavior or if maybe there is a difference between Mac/Windows.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--LocalData will skip all patching and use local game data and python files.
--NoSelfPatch will (on macOS) skip client patching, but depends on the server having the data files for all the game content (which is not guaranteed in the case of things like local Dockersand shards)

</ol>


<!-- No Linux client available, no point including this right now
<h3 id="running-linux">Running on Linux</h3>

<ol start="3">
<li><p>Open a terminal window in your MOUL-OS folder.</p></li>

<li><p>Run <code>plClient --LocalData</code> to start the client.</p></li>
Expand Down