SA-MP Forums

Go Back   SA-MP Forums > SA-MP Scripting and Plugins > Scripting Help > Tutorials

Reply
 
Thread Tools Display Modes
Old 09/04/2018, 03:09 PM   #1
[HLF]Southclaw
High-roller
 
[HLF]Southclaw's Avatar
 
Join Date: Apr 2009
Location: England
Posts: 4,947
Reputation: 1510
Default Yet Another Plugin Boilerplate - 2018 edition! (CMake/Docker/y_testing/sampctl)

Yet Another SA:MP Plugin Boilerplate

Introduction

I recently started a new plugin and I thought I’d write a bit about the project layout while it’s bare as I’ve put some effort into ensuring it’s a good boilerplate to start from. The project includes a quick and simple way to test plugins as well as a CMake setup and Y_Less’ plugin-natives usage.

It’s in no way an exhaustive “tutorial” per se but it should be a good place to get started. I noticed the tutorial by Kyosaur (which is a fantastic tutorial still) was showing a bit of age - that being said, you should still read it!

Code

The code can be seen/cloned/downloaded here

Requirements

Required
  • Visual Studio
    • I tested with 2017 but 2015 should work too.
  • Basic Command-Line Knowledge
    • I use Git-Bash for Windows but PowerShell or Cmd will work just as well.


Optional
  • Docker
    • this means you can compile the plugin for Linux while using a Windows
      machine (I assume most users here are on Windows). You could use a VM for
      this but Docker makes the process much simpler and automated via a couple of
      simple commands.

  • make
    • just because I put all the commands into a basic makefile for easier
      execution. You don’t need make as you can just open up the makefile and run
      the commands listed there manually.

  • sampctl
    • This makes testing the plugin on a SA:MP server a lot easier because the
      copying of the .dll and setup of the server is all automated. All you need
      to do is edit the .inc and write some test code into test.pwn and run
      make test-windows each time you edit the plugin!


Explanation of Every Important File

makefile

The makefile is the starting point, but it’s not related to the C++ code at all, it’s simply a task list for managing tests.

Run make test-setup before doing anything to get everything set up. You should only need to do this once. This runs sampctl server ensure inside test/ which uses the declarative samp.json file to automatically set up a SA:MP server instance inside of the test directory. Don’t worry, the .gitignore is already set up to ignore the server related files. It then runs sampctl package ensure to download the necessary dependencies for building the Pawn test script - this is just the SA:MP standard library and YSI for y_testing.

Run make test-windows to:
  • Copy the .dll file from test/plugins/Debug to test/plugins - an awkward
    side-effect of Visual Studio
  • build the Pawn test script to an .amx with y_testing
  • run the test script as a full SA:MP server instance


You should see Function called among the typical SA:MP boilerplate text and y_testing output.

src

This contains the C++ source code. Read the file head comments in order:
  • restful.cpp
  • common.hpp
  • natives.hpp
  • natives.cpp
  • impl.hpp
  • impl.cpp


CMakeLists.txt declares which files are relevant to the build process. I’m not a CMake expert so I’ll avoid going any further with this.

plugin-natives is a set of useful macros by Y_Less that make declaring plugin native functions way easier than the old way. See the plugin-natives repo for more info.

lib

This contains external dependencies. These are libraries required by this project, this includes cmake-modules by Zeex which provides some useful CMake stuff for working with SA:MP plugins and samp-plugin-sdk which is the software development kit for working with SA:MP itself. These are all declared as Git submodules (.gitmodules) and are updatable with git submodule update.

How do I Add New Dependencies?

Because this project uses CMake, if you want to use a dependency that is also using CMake you can simply git submodule add <url> lib/<name> then add it to the top-level CMakeLists.txt. It’s not always that straightforward though annoyingly but that’s just the way of the C++ world…

Dockerfile

If you’re new to docker, this file declares an “Image” which is an isolated filesystem running a particular operating system - in our case it derives from maddinat0r/debian-samp which is a Debian image built specifically for compiling SA:MP plugins by maddinat0r. This means you can compile an .so on Windows very easily by running make build-linux

Conclusion

I hope someone found this useful for their next plugin, if there are any actual problems in the boilerplate code/setup I shall create a new repo and cherry-pick the commit over so it can be modified for future users.
__________________
Tools:

Plugins:

Links:


Last edited by [HLF]Southclaw; 10/04/2018 at 02:26 PM.
[HLF]Southclaw is offline   Reply With Quote
Old 09/04/2018, 03:13 PM   #2
Kaperstone
Banned
 
Join Date: May 2011
Location: Russia
Posts: 3,348
Reputation: 824
Default Re: Yet Another Plugin Boilerplate - 2018 edition! (CMake/Docker/y_testing/sampctl)

Nice, thanks.
Kaperstone is offline   Reply With Quote
Old 09/04/2018, 08:35 PM   #3
Y_Less
Beta Tester
 
Y_Less's Avatar
 
Join Date: Jun 2008
Location: 629 - git.io/Y
Posts: 14,985
Reputation: 3150
Default Re: Yet Another Plugin Boilerplate - 2018 edition! (CMake/Docker/y_testing/sampctl)

One thing mentioned in Kyosaur's tutorial was that he couldn't find a way to remove the requirement of having a .def file for Windows (AFAIK you don't need it for Linux, but I don't know that for certain). If it is only Windows, it isn't required:

https://github.com/Y-Less/plugin-nat....hpp#L168-L184

https://github.com/Y-Less/plugin-nat...eFunc.hpp#L466
Y_Less is online now   Reply With Quote
Old 20/04/2018, 08:02 PM   #4
[HLF]Southclaw
High-roller
 
[HLF]Southclaw's Avatar
 
Join Date: Apr 2009
Location: England
Posts: 4,947
Reputation: 1510
Default Re: Yet Another Plugin Boilerplate - 2018 edition! (CMake/Docker/y_testing/sampctl)

Quote:
Originally Posted by Y_Less View Post
One thing mentioned in Kyosaur's tutorial was that he couldn't find a way to remove the requirement of having a .def file for Windows (AFAIK you don't need it for Linux, but I don't know that for certain). If it is only Windows, it isn't required:

https://github.com/Y-Less/plugin-nat....hpp#L168-L184

https://github.com/Y-Less/plugin-nat...eFunc.hpp#L466
Does the same go for the AMX events such as Load, Unload, ProcessTick, etc?

For as long as I can remember I've always had to add this in order to make those function calls fire:

EXPORTS
Supports
Load
Unload
AmxLoad
AmxUnload
ProcessTick

Does plugin-natives handle this internally or do I have to decl these in the source?
__________________
Tools:

Plugins:

Links:

[HLF]Southclaw is offline   Reply With Quote
Old 21/04/2018, 08:24 AM   #5
SyS
High-roller
 
SyS's Avatar
 
Join Date: Oct 2015
Posts: 1,992
Reputation: 467
Default Re: Yet Another Plugin Boilerplate - 2018 edition! (CMake/Docker/y_testing/sampctl)

Nice
SyS is offline   Reply With Quote
Old 21/04/2018, 09:40 AM   #6
[HLF]Southclaw
High-roller
 
[HLF]Southclaw's Avatar
 
Join Date: Apr 2009
Location: England
Posts: 4,947
Reputation: 1510
Default Re: Yet Another Plugin Boilerplate - 2018 edition! (CMake/Docker/y_testing/sampctl)

I've updated the boilerplate and removed the usage of plugin-natives (it's still a dependency) due to it not working well with GCC - hopefully this can get resolved at some point in the future but since most servers run on Linux, it's not much use having a boilerplate that only supports Windows plugins.
__________________
Tools:

Plugins:

Links:

[HLF]Southclaw is offline   Reply With Quote
Reply

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
[Tutorial] sampctl hello world - learn the sampctl workflow in 10 minutes [HLF]Southclaw Tutorials 4 14/05/2018 10:51 PM
(Own-Plugin) CMake build errors! Fratello Scripting Help 2 26/10/2017 04:18 PM
Anyone is using PAWN Boilerplate? Crystallize Everything and Nothing 6 23/02/2016 09:57 AM
[Tutorial] y_testing Misiur Tutorials 0 16/04/2015 06:38 PM


All times are GMT. The time now is 09:09 PM.


Powered by vBulletin® Version 3.8.6
Copyright ©2000 - 2018, Jelsoft Enterprises Ltd.