ControlPlane Hacking

Getting the code

ControlPlane is free, open source software hosted at https://github.com/dustinrue/ControlPlane. If you wish to build ControlPlane yourself you can do so by cloning the ControlPlane code to your computer. If you don't have git installed you will need to install either the GitHub client for Mac at http://mac.github.com/ which install a GUI client as well as the command line client or if you simply want the command line client installed you can get it from http://git-scm.com/download. If you need additional help with using Git GitHub is a great resource. You will find GitHub's documentation at http://help.github.com/.

Building ControlPlane

Generally speaking building ControlPlane is as simple as telling Xcode to build or run the project. However there are some submodules that need to be initialized and cloned. You can do this using terminal, entering the directory where ControlPlane is cloned to and issuing

git submodule init
git submodule update

Contributing to ControlPlane

If you wish to contribute to ControlPlane, maybe you've found a bug you wish to fix yourself or you've come up with a great new Evidence Source or Action, the first thing you should do is fork the ControlPlane code into your own repository. From there, create a new branch for your new changes and when finished, issue a pull request to me. If I like what you've done I'll add it. It's that simple.

To help you along some helpful tips have been posted below on how to create a new Evidence Source as well as a new Action.

Adding a new Evidence Source

1. Pick a short name for the evidence source; no spaces, starting with a letter (e.g. Foo)
2. Create an Objective-C class called FooEvidenceSource in the same style as the other sources. It should inherit from one of these:

   	EvidenceSource	GenericEvidenceSource	LoopingEvidenceSource	GenericLoopingEvidenceSource (the simplest)
   Use custom nib?	Yes	No	Yes	No
   Use simple loop?	No	No	Yes	Yes

   If using custom nib:

   • Create FooRule.nib
   • From your -init, call:

     	[super initWithNibNamed:@"FooRule"];
     			

   • Extend:

     	- (NSMutableDictionary *)readFromPanel;
     	- (void)writeToPanel:(NSDictionary *)dict usingType:(NSString *)type
     			

   If not using custom nib:

   • Override (implement):

     	- (NSString *)getSuggestionLeadText:(NSString *)type
     	- (NSArray *)getSuggestions
     			

   If using simple loop:

   • Extend:

     	- (void)doUpdate
     	- (void)clearCollectedData
     			

   If not using simple loop:

   • Override (implement):

     	- (void)start
     	- (void)stop
     			

3. Add mention of it in MPController.m, around line 61:

   	[appDefaults setValue:@"YES" forKey:@"EnableFooEvidenceSource"];
   

4. Add mention of it in the three places in EvidenceSource.m, from ~ line 268:

   	#import "FooEvidenceSource.h"
   	...
   	[FooEvidenceSource class],
   	...
   	NSLocalizedString(@"Foo", @"Evidence source");
   

Adding a new Action

1. Pick a short name for the action; no spaces, starting with a letter (e.g. Foo)
2. Create an Objective-C class called FooAction in the same style as the other actions
3. Add mention of it in the three places in Action.m (from around line 146):

   	#import "FooAction.h"
   	...
   	[FooAction class],
   	...
   	NSLocalizedString(@"Foo", @"Action type")