BKCommonLib/ForDevelopers
Introduction
This is a page where help is given for new and existing developers of BKCommonLib and everything related to it. If something needs to be redone or fixed, you can find information regarding it here.
BKCommonLib project structure
BKCommonLib is a maven project - you need to support it to contribute to it. If you are using the Eclipse IDE, you can install m2eclipse so you can properly import maven projects. To install this software, go to the marketplace in the Eclipse GUI and install it from there. See also: installation instructions.
Upon first looking over all packages and classes it may seem overwhelming - and it is. BKCommonLib is extremely large, but it has a fixed structure.
- Internal and server packages: try not to touch these, here is where all our CraftBukkit-specific logic resides
- Reflection: here is where we put all fields and methods contained within CraftBukkit so others can access it safely
- Proxies and Bases: here we store all base classes that can be extended or worked with. Includes math utility classes such as vectors
- Conversion: here are all convertors meant for converting one datatype to the other
- Collections: here we store all special type of collections, such as those that convert one type to the other dynamically
- Entity and Controller: all Entity-related utility classes which add new functionality, of which controllers
- Events: Some events plugins can use, fired by BKCommonLib. See also: internal.
- Localization and Permissions: speaks for itself, base classes for name given
- Config and NBT: speaks for itself, helper classes for dealing with configuration/file data storage/NBT tags
- Scoreboards: the Scoreboards API of BKCommonLib
- Tab: the Tab API of BKCommonLib
- Wrappers: for working with internal classes through a secure and non-reflection ridden layer
- Utils: All classes contain static utility methods that can be used for whatever purpose you seek
If you need to fix a bug or want to have a new feature, your first step is looking at which packages are or could be affected. Please don't make new packages for already covered things, it works confusing. If you plan on moving a class around, be sure to keep a (deprecated) redirecting proxy class behind so depending plugins don't stop working all of a sudden.
BKCommonLib build process
When first starting to work with it, you may notice that there are no package versions in the net.minecraft.server and org.bukkit.craftbukkit imports. The resulting build, however, does. How come? Well, to skip the process of manually updating all versions, we do multiple things:
- Use reflection where possible so we don't need these imports
- Use Spinot instead of CraftBukkit/Spigot to build against
- Use the 'maven-shade-plugin' to turn all imports to the proper versioned imports instead
In addition we have several other dependencies and respective repositories for per-plugin compatibility.
Jenkins build server and GitHub
We use GitHub to host our projects and have our own CI build server to build the GitHub projects on. Here is a checklist to see whether the Jenkins build server is ready to go:
- GitHub, Git server, Git client and other Git-related plugins are installed and set active (manage/manage plugins)
- JDK 6u38 and 7 are installed (manage/configure system)
- Git account information including a valid SSH key is set and hooks are set on manual (manage/configure system)
Per job (configuration):
- GitHub project path is set and Sourcecode management is set on 'git' and configured fully
- Repository URL and GitHub project path is the same (http://github.com/etc/etc)
- 'Build when changes are sent' checked, nothing else by default
- JDK 6 or 7 is selected properly for building the project (usually 6)
- Github plugin hook url (http://sitename.something/github-webhook/) is added to service hooks on the GitHub project
- Post-build step 'archive artifacts' is set (output: target/*.jar)
- Multiple branches? Be sure to specify 'origin/master' if needed!
Common errors and issues:
- Dependency issues on the server and not locally: delete the .m2/repository/* contents locally and refresh
- Compilation failure: change between different compiler versions until it works
- This is not what I wanted to build!: make sure it isn't building the wrong branch