Unverified Commit d0aa6af3 authored by Simon Esposito's avatar Simon Esposito Committed by GitHub
Browse files

Improve sample go module README (#378)

Change sample plugins README so that it supports Go 1.13 modules.
parent 488647e3
Loading
Loading
Loading
Loading
+35 −60
Original line number Diff line number Diff line
@@ -10,7 +10,7 @@ For more information and a discussion of the pros/cons with the Go runtime have

Here's the smallest example of a Go module written with the server runtime.

```
```go
package main

import (
@@ -32,90 +32,65 @@ To setup your own project to build modules for the game server you can follow th

1. Download and install the Go toolchain. It's recommended you follow the [official instructions](https://golang.org/doc/install).

2. Setup your GOPATH environment variable. Most use `$HOME/go` as the `$GOPATH`.

   You can temporarily setup the environment variable with `export` but for it to persist you should add it to your shell environment.
2. Setup a folder for your own plugin code.

   ```
   export GOPATH=$HOME/go
   ```

3. Use "go get" to download the server locally.

   ```
   go get -d github.com/heroiclabs/nakama
    ```bash
    mkdir -p $HOME/my-plugin-project
    cd $HOME/my-plugin-project
    ```

4. Build the game server from source if you want.
3. Init the go module for your plugin and add the nakama-common dependency.

    ```bash
    go mod init my-plugin-project
    go get -u "github.com/heroiclabs/nakama-common@v1.0.0"
    ```
   cd $GOPATH/src/github.com/heroiclabs/nakama
   env CGO_ENABLED=1 go build -trimpath
   ```

5. Setup a folder for your own server code.

   ```
   mkdir -p $GOPATH/src/some_project
   cd $GOPATH/src/some_project
   go get -u "github.com/heroiclabs/nakama-common"
   ```

6. You'll need to copy the main server dependencies into your project.
4. Develop your plugin code (you can use the [minimal example](#minimal-example) as a starting point) and save it within your plugin project directory with the `.go` extension.

   ```
   # Add some Go code. See an example above.
   go build --buildmode=plugin -trimpath -o ./modules/some_project.so
   ```
## Build & load process

   __NOTE__: It is not possible to build plugins on Windows with the native compiler toolchain but they can be cross-compiled and run with Docker. See more details below.
In a regular development cycle you will often recompile your plugin code and rerun the server.

7. Start the game server to load your plugin code. (Also make sure you run the database).
1. Develop and compile your code.

   ```
   $GOPATH/src/github.com/heroiclabs/nakama/nakama --runtime.path $GOPATH/src/plugin_project/modules
    ```bash
    go build --buildmode=plugin -trimpath -o modules/my-plugin.so
    ```

   __TIP__: You don't have to build and run Nakama from source. You can also download a prebuilt binary for your platform.
2. Use `--runtime.path` flag when you start the Nakama server binary to load your built plugin. (Note: also make sure you run the database).

## Build process

In a regular development cycle you will often recompile your code and rerun the server.

1. Develop and compile your code.

   ```
   go build --buildmode=plugin -trimpath
    ```bash
    ./nakama --runtime.path $HOME/my-plugin-project
    ```

2. Use "--runtime.path" when you start the server to load modules at startup.
   __TIP__: You can either build and run Nakama from source or you can download a prebuilt binary for your platform [here](https://github.com/heroiclabs/nakama/releases).

For more information on how the server loads modules have a look at [these](https://heroiclabs.com/docs/runtime-code-basics/#load-modules) docs. For general instructions on how to run the server give [these](https://heroiclabs.com/docs/install-start-server/#start-nakama) docs a read.

__HINT__: Due to a problem noted in this [issue](https://github.com/jaegertracing/jaeger/issues/422#issuecomment-360954600) it's necessary for the plugin to have the exact same vendored dependencies as the server binary for the final builds to be binary compatible. This should be resolved in the Go 1.12 release.

### Docker builds

It's often easiest to run the game server with Docker Compose. It will start the game server and database server together in the right sequence and wraps the process up into a single command. You'll need the Docker engine installed to use it.

For Windows development and environments where you want to use our official Docker images to run your containers we provide a container image to help you build your code.

1. Use the Docker plugin helper container to compile your project. In PowerShell:
1. Use the Docker plugin helper container to compile your project (works for bash/PowerShell):

   ```
   cd $GOPATH/src/plugin_project # Your project folder. See instructions above.
   docker run --rm -v "${PWD}:/tempbuild" -w "/tempbuild" heroiclabs/nakama-pluginbuilder:2.7.0 build --buildmode=plugin -trimpath -o ./modules/plugin_project.so
    ```bash
    cd $HOME/my-plugin-project # Your project folder. See instructions above.
    docker run --rm -w "/builder" -v "${PWD}:/builder" heroiclabs/nakama-pluginbuilder:2.7.0 build  --buildmode=plugin -trimpath -o ./modules/my-plugin.so
    ```

   In the command above we bind-mount your current folder into the container and use the Go toolchain inside it to run the build. The output artifacts are written back into your host filesystem.

2. Use our official Docker Compose [file](https://heroiclabs.com/docs/install-docker-quickstart/#using-docker-compose) to run all containers together and load in your custom module.

   ```
   docker-compose -f ./docker-compose.yml up
    __NOTE:__ You should copy the `.so` files generated in step 1. to the `/modules` folder of your Nakama source files and then run the command below from the Nakama root directory.

    ```bash
    docker-compose up
    ```

   By default the server will be started and look in a folder relative to the current dir called "./modules" to load code.
   By default the server will be started and look in a folder relative to the current dir called "./modules" to load the plugins.

   __TIP__: Use the same version of your plugin builder image as used in the Docker Compose file for the server version. i.e. "heroiclabs/nakama:2.3.1" <> "heroiclabs/nakama-pluginbuilder:2.3.1"