I’ve been asked how to begin developing modules for farmOS, so I decided to write up a quick forum post, in hopes that it may be useful for others.
This is meant to compliment the official farmOS 2.x Module Development Guide.
Also note that this is specifically for farmOS server module development… not “Field Modules” for farmOS Field Kit - which are still a developing concept (@jgaehring can provide some intros to that process when the time is right).
We have a pretty elegant layered development model - building on that of the Drupal community/platform itself. If you are coming to farmOS as a new developer (and without any experience with Drupal) it helps to understand the options that are available.
If you want ultimate freedom, then you can create your own custom module (eg:
farm_myfarmname) and play around however you want. This module can provide new asset types, log types, plan types, etc… depend on other modules (eg:
farm_fungi)… override configuration from other modules… add pages, forms, etc etc etc… ultimate freedom! This is a great place to start experimenting, as it has no affect/considerations with regard to the “official” modules or farmOS core itself. You’re basically building your own layer on top to do exactly what you want/need.
Custom modules can be very specific to your needs. And as such, it often doesn’t make sense for others to use them. They can be kept private (not published to public repository), and only installed on your individual instance.
The next level up is “contrib modules”, which is just Drupal parlance for a module that isn’t part of Drupal core, or in our case farmOS core - and often means it’s “community maintained”. These include modules like Fungi, Organic, Grazing, etc.
The other end of that spectrum is contributing patches or pull requests to farmOS core itself. We also maintain a number of “official contrib” modules (under the farmOS GitHub organization: farmOS · GitHub).
Contributing to these has more of a strict process to it, and therefore more restrictions and considerations. We try to keep the core/official code as simple and easy to maintain as we can - and critically: as general as possible, so that it fits the needs of a wide audience.
The combination of these three approaches is a great balance, because it keeps the core maintenance of official code manageable, while allowing for ultimate freedom for experimentation in the “contrib” and “custom” space. This also allows for a process whereby code from custom/contrib can “move upstream” to core/official code over time. So if someone comes up with a really great solution in their own module, and it solves a general need that others in the community see value in, they can propose that it be considered for inclusion in “upstream” code.
Custom to contrib
In many cases, it may make sense for code to start in a custom module, and then if it is general and useful to others it can be published as a contrib module. Or, if it modifies/extends an existing contrib module it can propose moving certain parts to the upstream project.
Contrib/custom to core
If an improvement is so general that it makes sense to include in farmOS core itself, then it can be proposed for inclusion in a similar way.
The first step to getting started is to set up a local development environment: Getting started - farmOS 2.x Docs
Then, decide where you want to start: custom, contrib, or core. In most cases the easiest place to start is a custom module.
To create your first custom module, create a new directory inside
www/web/sites/all/modules with the name of your module. Module names must be all lowercase alphanumeric, with underscores. Standard practice is to prefix your module name with
farm_ to designate that it is a farmOS module (not a more general Drupal module). Then, within that directory, create a file called
[modulename].info.yml. This simply tells Drupal that the module exists.
name: My custom farmOS module description: This is a description of what my module does. type: module package: farmOS Custom core_version_requirement: ^9
That’s it! Now when you go to https://[my-farmOS-hostname]/admin/modules you will see your custom module and be able to enable it.
What you do from there depends on what your goals are… feel free to ask questions here if it is not already covered in the module development guide.
If you want to work with an existing module directly, you can fork it’s repository on GitHub (or wherever it lives), and clone it to your
sites/all/modules directory. Then you can make changes, commits, and create Pull Requests like normal.
If you believe your changes belong in farmOS core itself, start by opening an issue to describe your proposal.
The farmOS development environment automatically checks out the farmOS Git repository in
www/web/profiles/farm - so you can create a branch there, add your remote fork, etc.
If you plan to contribute changes to core or contrib modules, it’s always a good idea to open an issue first that describes what you’d like to do, and work with the maintainers to make sure that it makes sense. farmOS core and official modules strive to be both general (applicable to many use-cases), and maintainable (the least amount of code to achieve agreed upon goals). So before you put a lot of effort into changes, be sure that they have a chance for inclusion upstream in the first place. If not, they can live in your own custom or contrib modules instead. This is another reason why it’s often best to start in a custom module… it allows you to work quickly to meet your own needs, without the extra considerations of upstream contributions, while still leaving the possibility open to moving upstream in the future, if applicable.
The farmOS Module Development Guide aims to provide some basic information about farmOS module development. It focuses on farmOS-specific concepts (as well as a basic intro to Drupal module file structure).
For information about Drupal module development more generally (of which farmOS modules are a subset), refer to the official Drupal Module Developer’s Guide.
There are a lot of aspects and possibilities to Drupal module development, which we cannot possibly cover in detail here or in our own documentation. So we try to keep our docs focused on the farmOS-specific details. But feel free to ask questions in this thread, or post links to additional resources that you found helpful in your explorations!
Welcome to farmOS development!