Contributor procedure for adding new agent with example
- Create a repository with new agent anywhere outside the 42ITy
Add the following line to the description to avoid early commits:
PLEASE DO NOT FORK this repository yet as it will get merged into the 42ITy organization and may be renamed.
- Follow 42ITy Contributor guide.
- Make sure that your codebase conforms to at least the Minimal Requirements listed below; it is of course preferable to score the Bonus Points as well, if only to automate verification that the minimal requirements are met (and stay met, as the codebase evolves).
- Create an issue on FTY repository on GitHub pointing at your repository and providing some information on your new agent, especially notifyng if it needs any special dependencies not already pulled by existing components (and suggest what corresponding run-time and development package names might be in Debian/Ubuntu, and in RHEL/CentOS/OpenSUSE worlds).
- As soon as you have the approval, your repository with new agent will be moved under 42ITy organization.
- Once your new agent has been moved to a repository under the 42ITy organization, please delete your own repository and fork the one from the 42ITy to continue with your contributions to the ecosystem.
Reminder for 42ITy project maintainers:
- After cloning the new repository, make sure to rescan Travis CI for the 42ITy organization and enable testing of the newly added component.
- After cloning the repo, make sure to add the submodule, build recipe entry in
Makefile, and perhaps additional required Ubuntu packages in
.travis.yml, to 42ITy/FTY build framework.
Creating new agent
Must be buildable by standard autotools procedure, .i.e:
./autogen.sh && ./configure && ./make
maketargets must work
check- (unit) tests
memcheck- same as above, but ran under
valgrindto make sure no memory leaks are introduced
install- make sure all expected files are installable
Working debian packaging under
- Target for
make distcheckshould pass as well, as the test for clarity of your
- Travis CI tests (
valgrind) should be defined and pass green "honestly". You may disable the
cmaketests and not commit the pre-generated
*.cmakefiles, as our project does not currently plan to use that tool-chain; you can even add them to the
.gitignorelist of your new component. You can verify that tests pass before contributing the new agent by enabling Travis CI integration for your original development repository.
There are some prerequisities that are not mandatory but will make your (and our) life so much easier. Most of these are documented in the 42ITy Contributor guide.
A very helpful tool is zproject, since it will generate everything from Requirements sections for you, even packaging metadata and self-testing capabilities.
The example agent has been written to show how to:
- connect to malamute messaging broker
- use STREAM pattern to receive messages from system streams
- use STREAM pattern to publish to system streams
- use MAILBOX pattern to receive messages from other peers
- use MAILBOX pattern to send messages to other peers
Any new agent will want to do at least one of those things. That is, any new agent will want to either feed something to the system or listen to system and react to some events, or entities, or both.
The example itself doesn't make much real-world sense, but demonstrates these goals perfectly:
- fty-example agent is subscribed to ASSETS stream (to receive asset messages, i.e. when anything is being done with assets.)
- fty-example agent publishes to ALERTS stream (to publish alert messages)
- when an asset message arrives on ASSETS stream using STREAM pattern, fty-example agent will extract name of asset and publish an alert message to ALERTS stream using STREAM pattern
- when fty-example agent receives a message from any peer using MAILBOX pattern which is one string frame HELLO, it will reply back to the same exact peer with one string frame message WORLD.
There are tests inside the repo showing how we can easily test this functionality using just the agent interface.