You will need:
- Git
- Maven
- JDK 17 or greater
These can be installed through your package manager of choice.
Run git clone https://github.com/A248/LibertyBans.git && cd LibertyBans && mvn package
This will clone the source repository and start the Maven build in the cloned directory.
When the build is complete, the jar at bans-distribution/executable/target/LibertyBans_version.jar
can run as a plugin on any supported platform.
You can use any IDE you choose. Simply import the project and ensure it is configured to use Maven.
The project is split into several Maven modules. You will want to make sure that your IDE recognizes these modules.
Please use tabs. Otherwise, try to follow the surrounding code style.
Try to avoid nesting when working with CompletableFuture
. If you place callbacks on a new line, the indentation becomes extreme. For example, prefer this:
return selector.getActivePunishmentById(id).thenCompose((optPunishment) -> {
// Callback
});
To this:
return selector.getApplicablePunishment(id)
.thenCompose((optPunishment) -> {
// Callback
// Notice the extra indentation
});
If necessary, break the arguments to the method creating the future onto a new line:
return selector.getApplicablePunishment(
uuid, address, PunishmentType.BAN
).thenCompose((optPunishment) -> {
// Callback
});
- The API:
bans-api
- Startup code which sets up classloader isolation and launches the rest of the plugin:
bans-boostrap
- Platform-specific plugins:
bans-env-bungeeplugin
(extends Plugin)bans-env-spigotplugin
(extends JavaPlugin)bans-env-spongeplugin
(@Plugin)bans-env-velocityplugin
(@Plugin)
The following modules comprise the core implementation:
- The core, platform-agnostic implementation:
bans-core
- Platform-specific implementation code:
bans-env-bungee
bans-env-spigot
bans-env-sponge
bans-env-velocity
- LibertyBans starts with the platform-specific plugin, which calls into the boostrap module.
- The bootstrap module sets up classloader isolation, downloads or extracts dependencies as necessary, then launches the core.
- The core creates the configuration and connects to the database.
- The platform-specific implementation registers commands and listeners.
For example, on Velocity:
bans-env-velocityplugin
| | | |
V V V V
bans-bootstrap
| | | | // Plugin class loader
--------- V V V V -------------------------------------
bans-core // Isolated class loader
/ | \
/ | \
V V V
Config Database bans-env-velocity
The implementation modules are placed in an isolated classloader. This classloader separation means that plugin classes are visible to implementation classes, but implementation classes are not visible to plugin classes.
Addon modules, under bans-core-addons
, may be installed at user preference.
Installed addon jars are loaded by the isolated classloader, functioning as if part of bans-core
.
LibertyBans is distributed in two ways.
The release distribution is a lightweight jar which downloads its dependencies at runtime, with SHA-512 hash verification. This jar is published to SpigotMC and Github Releases.
The development distribution is intended for compiling and running from source. It uses a nested jar format and extracts these jars at runtime.
You are encouraged to write unit and integration tests!
Unit tests are run as part of the Maven build. mvn test
will execute them.
Using mvn clean verify
will build and run all tests, including integration tests. This is the same command used by the Jenkins CI.
The integration tests optionally rely on docker to start a temporary MariaDB database. Points of note:
- If you do not have docker installed, and you do not want to install it, that is entirely fine. The build will gracefully skip the tests which require docker. This does not mean no tests will run; some tests contact in-memory databases (like HSQLDB) which do not require docker.
- The presence of docker is automatically detected on UNIX.
- If you want to run the tests on Windows, you will need to enable the
docker-enabled
build profile. For example,mvn clean verify -Pdocker-enabled
. - If you want to disable this automatic detection, you can disable the
docker-enabled
build profile. For example,mvn clean verify -P-docker-enabled
.
- If you want to run the tests on Windows, you will need to enable the
- Random ports are selected for use in the range 40,000-50,000. You may need to tweak your firewall settings accordingly; in some cases you may need to enable outgoing connections on ports
3306
for MySQL and MariaDB,5432
for PostgreSQL, and26257
for CockroachDB as well (oddly enough).
If you would prefer not to run the integration tests yourself, that's fine. Simply let the CI take care of it.
See the section "Compiling and running the current source"
I make releases with a few steps:
mvn versions:set -DnewVersion={theNextVersion}
build/check-hashes.sh
to see the new dependency hashes for internal dependencies- Update the dependency hashes in the parent pom
- Perform the deployment with
mvn clean deploy -Pcheck-hash,-docker-enabled -DskipTests -Dinvoker.skip=true
- Commit and tag the results.