Skip to content
Permalink
Browse files

Improve sample go module README

Change sample plugins README so that it supports Go 1.13 modules.
  • Loading branch information...
sesposito committed Sep 20, 2019
1 parent 488647e commit 01aa39845e389a8d9a8d79be395f02febdd52519
Showing with 35 additions and 60 deletions.
  1. +35 −60 sample_go_module/README.md
@@ -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.

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

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

```
go get -d github.com/heroiclabs/nakama
```

4. Build the game server from source if you want.

```
cd $GOPATH/src/github.com/heroiclabs/nakama
env CGO_ENABLED=1 go build -trimpath
```
2. Setup a folder for your own plugin code.

5. Setup a folder for your own server code.
```bash
mkdir -p $HOME/my-plugin-project
cd $HOME/my-plugin-project
```

```
mkdir -p $GOPATH/src/some_project
cd $GOPATH/src/some_project
go get -u "github.com/heroiclabs/nakama-common"
```
3. Init the go module for your plugin and add the nakama-common dependency.

6. You'll need to copy the main server dependencies into your project.
```bash
go mod init my-plugin-project
go get -u github.com/heroiclabs/nakama-common@v1.0.0
```
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).

```
$GOPATH/src/github.com/heroiclabs/nakama/nakama --runtime.path $GOPATH/src/plugin_project/modules
```

__TIP__: You don't have to build and run Nakama from source. You can also download a prebuilt binary for your platform.
1. Develop and compile your code.

## Build process
```bash
go build --buildmode=plugin -trimpath -o modules/my-plugin.so
```

In a regular development cycle you will often recompile your code and rerun the server.
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).

1. Develop and compile your code.
```bash
./nakama --runtime.path $HOME/my-plugin-project
```

```
go build --buildmode=plugin -trimpath
```

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):

```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
```

```
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
```

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"

0 comments on commit 01aa398

Please sign in to comment.
You can’t perform that action at this time.