Skip to content

Commit f89d04a

Browse files
TelroshanTelroshan
committed
Update README.md
1 parent 33fcf6b commit f89d04a

File tree

1 file changed

+193
-30
lines changed

1 file changed

+193
-30
lines changed

‎README.md‎

Lines changed: 193 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,169 @@
11
# go-sfml
22

3-
Up-to-date Go bindings for [SFML](http://www.sfml-dev.org), the Simple and Fast Multimedia Library.
3+
Go bindings for [SFML](http://www.sfml-dev.org), the Simple and Fast Multimedia Library, version [2.5.1](https://www.sfml-dev.org/changelog.php#sfml-2.5.1)
4+
5+
Originally made by [teh-cmc](https://github.com/teh-cmc)
46

57
These bindings *are entirely generated* using [SWIG](http://www.swig.org/) and the official [C bindings of SFML](https://www.sfml-dev.org/download/csfml/).
6-
Hence they should be fairly easy to maintain & keep in sync with future releases from upstream.
8+
Hence they should be fairly easy to maintain & keep in sync with future releases from upstream
9+
10+
## Table of Contents
711

812
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
913
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
1014

11-
**Table of Contents**
12-
- [go-sfml](#go-sfml)
13-
- [Portability](#portability)
14-
- [Requirements](#requirements)
15+
16+
- [Portability](#portability)
17+
- [Usage](#usage)
1518
- [Installation](#installation)
16-
- [Usage](#usage)
17-
- [Modules](#modules)
18-
- [Example](#example)
19-
- [License](#license-)
19+
- [First setup](#first-setup)
20+
- [Get the module](#get-the-module)
21+
- [Troubleshooting](#troubleshooting)
22+
- [Error: `SFML/Window.h: No such file or directory`](#error-sfmlwindowh-no-such-file-or-directory)
23+
- [Error: `csfml-window-2.dll could not be found`](#error-csfml-window-2dll-could-not-be-found)
24+
- [Bat script](#bat-script)
25+
- [API](#api)
26+
- [Modules](#modules)
27+
- [Examples](#examples)
28+
- [Basic example](#basic-example)
29+
- [Other examples](#other-examples)
30+
- [Building go-sfml](#building-go-sfml)
31+
- [Download & compile SFML + CSFML](#download--compile-sfml--csfml)
32+
- [Troubleshooting](#troubleshooting-1)
33+
- [Error: `/usr/bin/env: ‘bash\r’: No such file or directory`](#error-usrbinenv-bashr-no-such-file-or-directory)
34+
- [Error: `CMake Error [...] Could not find X11` _(or a similar error with just another name instead of `X11`)_](#error-cmake-error--could-not-find-x11-or-a-similar-error-with-just-another-name-instead-of-x11)
35+
- [Setup swig](#setup-swig)
36+
- [Option 1 - Install it from your package manager](#option-1---install-it-from-your-package-manager)
37+
- [Option 2 - Build it locally](#option-2---build-it-locally)
38+
- [Troubleshooting](#troubleshooting-2)
39+
- [Error: `/usr/bin/env: ‘bash\r’: No such file or directory`](#error-usrbinenv-bashr-no-such-file-or-directory-1)
40+
- [Error: `Cannot find pcre-config script from PCRE (Perl Compatible Regular Expressions)`](#error-cannot-find-pcre-config-script-from-pcre-perl-compatible-regular-expressions)
41+
- [Build go bindings](#build-go-bindings)
42+
- [Troubleshooting](#troubleshooting-3)
43+
- [Error: `/usr/bin/env: ‘bash\r’: No such file or directory`](#error-usrbinenv-bashr-no-such-file-or-directory-2)
44+
- [Error: `swig: command not found`](#error-swig-command-not-found)
45+
- [Error: `Unable to find 'swig.swg'`](#error-unable-to-find-swigswg)
46+
- [Error: `patchelf: command not found`](#error-patchelf-command-not-found)
2047

2148
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2249

2350
---
2451

2552
## Portability
2653

27-
I have only tested these on darwin/amd64, using the latest macOS Sierra.
28-
Feel free to open issues and/or PRs if you're running into problems on other platforms.
54+
I have only tested these on Windows 10
55+
56+
Feel free to open issues and/or PRs if you're running into problems on other platforms
2957

30-
## Requirements
58+
## Usage
3159

32-
- [SFML 2.4.0](https://www.sfml-dev.org/download/sfml/2.4.0)
33-
- [CSFML 2.4](https://www.sfml-dev.org/download/csfml/)
60+
### Installation
61+
#### First setup
62+
I'll cover Windows in this section _(I build go-sfml using [WSL](https://docs.microsoft.com/en-us/windows/wsl/install), but build my go apps on Windows)_
3463

35-
## Installation
64+
1. Download [CSFML 2.5.1](https://www.sfml-dev.org/download/csfml/) and extract it wherever you like _(assuming `C:\CSFML_2.5.1` for the next steps)_. I'm downloading the 64 bits version since I'm on a 64 bits Windows
65+
2. Download and install the [GCC compiler](https://gcc.gnu.org/install/binaries.html) _(in my case, the [mingw x86_64-win32-sjlj](https://github.com/niXman/mingw-builds-binaries/releases) one)_
66+
3. We now need to define the `CGO_CFLAGS` and `CGO_LDFLAGS` environment variables so the linker knows where the CSFML headers and compiled libraries are at
3667

37-
Assuming both libraries and their header files are correctly installed and available through the standard paths of your system:
68+
Assuming CSFML is extracted at `C:\CSFML_2.5.1`, we can run the following in a command line :
3869
```
39-
$ go get -u gopkg.in/teh-cmc/go-sfml.v24/...
70+
set CGO_CFLAGS="-IC:\CSFML_2.5.1\include"
71+
set CGO_LDFLAGS="-LC:\CSFML_2.5.1\lib\gcc"
4072
```
73+
Feel free to set those variables system-wide so you don't have to define them on the fly everytime
4174

42-
That's it!
75+
Notice the **-I** and **-L** before the paths, with no whitespace in between
4376

44-
## Usage
77+
4. Build the example to ensure your setup is working
78+
```bash
79+
cd examples/basic_window
80+
go get && go build
81+
```
82+
5. Copy the CSFML DLLs next to your executable, for the basic example we only need `csfml-window-2.dll` and `csfml-graphics-2.dll` that you'll find into `C:\CSFML_2.5.1\bin`
83+
6. Run the exe, a red window should appear!
84+
#### Get the module
85+
For future projects, simply run
86+
```bash
87+
go get github.com/telroshan/go-sfml/v2
88+
```
89+
And import the modules you need
90+
```Go
91+
import (
92+
"github.com/telroshan/go-sfml/v2/graphics"
93+
"github.com/telroshan/go-sfml/v2/window"
94+
"github.com/telroshan/go-sfml/v2/system"
95+
"github.com/telroshan/go-sfml/v2/audio"
96+
)
97+
```
98+
#### Troubleshooting
99+
##### Error: `SFML/Window.h: No such file or directory`
100+
&#8594; Make sure you have downloaded the CSFML version that matches your system _(don't download the 32 bits one if you're on a 64 bits Windows)_
101+
102+
&#8594; Make sure you included the subfolder matching your compiler _(gcc here)_ for `CGO_LDFLAGS`, and didn't make it point to the `lib` root folder itself
103+
104+
&#8594; Make sure you defined the environment variables in the same command line that you ran `go build` into _(the variables defined with the [`set`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) command won't exist outside of the command line they've been set into)_
105+
106+
&#8594; Make sure you typed the variable names correctly, i.e `CGO_CFLAGS` and `CGO_LDFLAGS`
45107

46-
The generated APIs very closely follow those of [SFML's C bindings](https://www.sfml-dev.org/download/csfml/): the [tutorials](http://www.sfml-dev.org/tutorials/) & [documentation](http://www.sfml-dev.org/documentation/) available for the official C++ implementation, as well as an editor with a well configured Go-autocompletion, will get you a long way.
108+
&#8594; Make sure you didn't invert the paths between the two variables. `CGO_CFLAGS` should point to the `include` folder whereas `CGO_LDFLAGS` should point to the libs
109+
110+
&#8594; Make sure you made no typo with the syntax of -I and -L for those variables
111+
##### Error: `csfml-window-2.dll could not be found`
112+
&#8594; You probably didn't copy CSFML DLLs next to your executable, as mentioned in step 5
113+
114+
### Bat script
115+
Alternatively to steps 3 to 5 from the [previous section](#installation), you could use a bat script to automate that process for you, such as [the one in the basic window example](https://github.com/Telroshan/go-sfml/blob/main/examples/basic_window/build.bat)
116+
```bat
117+
@ECHO OFF
118+
119+
rem This script sets the environment variables to be able to build the app, and copies the CSFML DLLs over if there aren't any in the folder
120+
121+
rem Edit the CSFML_PATH variable to match the path of your CSFML installation
122+
set CSFML_PATH=C:\CSFML_2.5.1
123+
rem Edit the COMPILER_NAME variable if you're not using gcc
124+
set COMPILER_NAME=gcc
125+
126+
set CGO_CFLAGS="-I%CSFML_PATH%\include"
127+
set CGO_LDFLAGS="-L%CSFML_PATH%\lib\%COMPILER_NAME%"
128+
129+
go get
130+
if %ERRORLEVEL% NEQ 0 (echo go get failed && exit /b %ERRORLEVEL%)
131+
132+
go build
133+
if %ERRORLEVEL% NEQ 0 (echo go build failed && exit /b %ERRORLEVEL%)
134+
135+
echo Build complete
136+
137+
if not exist "%~dp0*.dll" (
138+
echo No DLLs in folder, getting them from CSFML folder
139+
xcopy /s "%CSFML_PATH%\bin" "%~dp0"
140+
if %ERRORLEVEL% NEQ 0 (echo failed to copy DLLs && exit /b %ERRORLEVEL%)
141+
)
142+
```
143+
144+
### API
145+
The generated APIs very closely follow those of [SFML's C bindings](https://www.sfml-dev.org/download/csfml/): the [tutorials](http://www.sfml-dev.org/tutorials/) & [documentation](http://www.sfml-dev.org/documentation/) available for the official C++ implementation, as well as an editor with a well configured Go-autocompletion, will get you a long way
47146

48147
### Modules
49148

50-
The original C & C++ implementations of SFML come with 5 modules: [*Audio*](https://www.sfml-dev.org/documentation/2.4.0/group__audio.php), [*Graphics*](https://www.sfml-dev.org/documentation/2.4.0/group__graphics.php), [*Network*](https://www.sfml-dev.org/documentation/2.4.0/group__network.php), [*System*](https://www.sfml-dev.org/documentation/2.4.0/group__system.php) and [*Window*](https://www.sfml-dev.org/documentation/2.4.0/group__window.php).
149+
The original C & C++ implementations of SFML come with 5 modules: [*Audio*](https://www.sfml-dev.org/documentation/2.4.0/group__audio.php), [*Graphics*](https://www.sfml-dev.org/documentation/2.4.0/group__graphics.php), [*Network*](https://www.sfml-dev.org/documentation/2.4.0/group__network.php), [*System*](https://www.sfml-dev.org/documentation/2.4.0/group__system.php) and [*Window*](https://www.sfml-dev.org/documentation/2.4.0/group__window.php)
51150

52151
Of these 5 modules:
53152
- ***Audio***, ***Graphics*** & ***Window*** come with complete Go packages counterparts
54153
- ***System*** also has a dedicated Go package, but only contains the `sfVector2` & `sfVector3` classes; everything else is already available in one form or another in Go's standard library
55154
- ***Network*** has been entirely discard, use Go's standard library instead
56155

57-
### Example
58-
156+
### Examples
157+
#### Basic example
59158
Here's a straightforward example of creating a window and handling events:
60159
```Go
61160
package main
62161

63162
import (
64163
"runtime"
65164

66-
"gopkg.in/teh-cmc/go-sfml.v24/graphics"
67-
"gopkg.in/teh-cmc/go-sfml.v24/window"
165+
"github.com/telroshan/go-sfml/v2/graphics"
166+
"github.com/telroshan/go-sfml/v2/window"
68167
)
69168

70169
func init() { runtime.LockOSThread() }
@@ -133,8 +232,72 @@ int main() {
133232
}
134233
```
135234

136-
## License ![License](https://img.shields.io/badge/license-Zlib-blue.svg?style=plastic)
137-
138-
The Zlib/libpng - see [LICENSE](./LICENSE) for more details.
235+
#### Other examples
236+
You'll find other examples in the [examples folder](https://github.com/Telroshan/go-sfml/tree/main/examples)
237+
1. [Basic window](https://github.com/Telroshan/go-sfml/tree/main/examples/basic_window) : just the same as above
238+
2. [Tennis](https://github.com/Telroshan/go-sfml/tree/main/examples/tennis) : go version of [SFML's tennis example](https://github.com/SFML/SFML/tree/master/examples/tennis)
239+
240+
Feel free to open PRs if you have any example you'd like to share!
241+
242+
## Building go-sfml
243+
If you just want to use go-sfml for SFML 2.5.1 into your go project, you may want to read the [Usage section](#usage) instead
244+
245+
If you want to build your own bindings for a different version of SFML, then this section is for you!
246+
247+
_Note_: the following steps were realized in Windows' [Ubuntu bash](https://docs.microsoft.com/en-us/windows/wsl/install). Feel free to open issues and/or PRs if you're running into problems on other Unix-based platforms
248+
249+
### Download & compile SFML + CSFML
250+
1. Install [SFML dependencies](https://www.sfml-dev.org/tutorials/2.5/compile-with-cmake.php#installing-dependencies) first
251+
2. Run the `sfml.sh` script to handle the process of downloading SFML/CSFML and compiling them for you
252+
253+
#### Troubleshooting
254+
##### Error: `/usr/bin/env: ‘bash\r’: No such file or directory`
255+
&#8594; You're probably having [CRLF](https://developer.mozilla.org/en-US/docs/Glossary/CRLF) issues _(happened to me when cloning the repo on Windows initially before switching to WSL)_
256+
257+
&#8594; Use `dos2unix` _(install it if you don't have the command)_ on the 3 scripts : `dos2unix sfml.sh swig.sh build.sh`
258+
259+
##### Error: `CMake Error [...] Could not find X11` _(or a similar error with just another name instead of `X11`)_
260+
<pre>
261+
<b>Could not find</b> X11
262+
Call Stack (most recent call first):
263+
src/SFML/Window/CMakeLists.txt (find_package)
264+
</pre>
265+
&#8594; You probably didn't install every [SFML dependency](https://www.sfml-dev.org/tutorials/2.5/compile-with-cmake.php#installing-dependencies). Don't forget the development headers as well! For example on Ubuntu, you'll want to install `libx11-dev`, `xorg-dev`, `libudev-dev`, and so on
266+
267+
### Setup swig
268+
#### Option 1 - Install it from your package manager
269+
1. Depending on your platform, you may simply download the available package. For example on Ubuntu, `sudo apt install swig`
270+
#### Option 2 - Build it locally
271+
1. Run `sudo apt install libpcre3-dev` _(swig requires this package)_
272+
2. Run the `swig.sh` script
273+
3. Check where swig thinks its lib is, by running `./swig/swig -swiglib`. It should output <code><i>${path/to/go-sfml}</i>/swig/Lib</code>
274+
4. If the output doesn't match, fix that by overriding the `SWIG_LIB` environment variable. You may run <code>export SWIG_LIB=<i>${path/to/go-sfml}</i>/swig/Lib</code> to override the var just for your current session, or [make it persistent](https://help.ubuntu.com/community/EnvironmentVariables#Persistent_environment_variables)
275+
5. Run `./swig/swig -swiglib` again to ensure swig has the correct path to its own lib
276+
6. Update the `build.sh` script and change the [line 23](https://github.com/telroshan/go-sfml/blob/master/build.sh#L23) : the script is looking for a [global command](#option-1---install-it-from-your-package-manager) `swig`, you must replace that path by `./swig/swig` to use the local build instead
277+
#### Troubleshooting
278+
##### Error: `/usr/bin/env: ‘bash\r’: No such file or directory`
279+
&#8594; You're probably having [CRLF](https://developer.mozilla.org/en-US/docs/Glossary/CRLF) issues _(happened to me when cloning the repo on Windows initially before switching to WSL)_
280+
281+
&#8594; Use `dos2unix` _(install it if you don't have the command)_ on the 3 scripts : `dos2unix sfml.sh swig.sh build.sh`
282+
##### Error: `Cannot find pcre-config script from PCRE (Perl Compatible Regular Expressions)`
283+
&#8594; You probably didn't install libpcre3-dev as mentioned in step 1. Run `sudo apt install libpcre3-dev` and try again
284+
285+
### Build go bindings
286+
1. Run `sudo apt install patchelf` _(the build script uses this package to fix the missing links from the built CSFML libraries to the SFML ones)_
287+
2. Run `build.sh`
288+
#### Troubleshooting
289+
##### Error: `/usr/bin/env: ‘bash\r’: No such file or directory`
290+
&#8594; You're probably having [CRLF](https://developer.mozilla.org/en-US/docs/Glossary/CRLF) issues _(happened to me when cloning the repo on Windows initially before switching to WSL)_
291+
292+
&#8594; Use `dos2unix` _(install it if you don't have the command)_ on the 3 scripts : `dos2unix sfml.sh swig.sh build.sh`
293+
##### Error: `swig: command not found`
294+
&#8594; You probably either did not [install the `swig` package](#option-1---install-it-from-your-package-manager), or [built it locally](#option-2---build-it-locally) but forgot to follow the step 6 to update the path used by the `build.sh` script
295+
##### Error: `Unable to find 'swig.swg'`
296+
&#8594; You probably went for the swig [local build](#option-2---build-it-locally), but didn't check for its lib path. Please follow steps 3 to 5 of that section
297+
##### Error: `patchelf: command not found`
298+
&#8594; You probably didn't install `patchelf` as mentioned in step 1
299+
300+
You're now ready to go!
301+
302+
Feel free to open issues and/or PRs if you're running into problems that are not mentioned in the troubleshooting sub-sections
139303

140-
Copyright (c) 2017 Clement 'cmc' Rey <cr.rey.clement@gmail.com> [@teh_cmc](https://twitter.com/teh_cmc)

0 commit comments

Comments
 (0)