This is the second Sample about Activating your own code for use with ActiveDeveloper. In this Sample we will move further than we did in the previous Sample - and show how to Activate more then just a single class for incremental editing with ActiveDeveloper. The case study is WebBrowser, the main example using the new WebKit. We have provided 3 folders that contain the WebBrowser app in various stages of activation.
The Developer application FileMerge.app gives you a good overview of what changes are made from Step to Step. | ![]() |
WebBrowser consists of two classes
you type a URL in the top field and press "Enter", and WebBrowser will load the URL and display it's contents in the lower WebView using the new WebKit.
If you want to try for yourself - use Xcode to create a new Project WebBrowser in the CocoaDemos folder, then copy the contents of Step 0 into this new Xcode project and add the files to the Xcode project - arranging them into suitable groups as usual. You will normally already have this done for your own projects. Now build the new project with Xcode and try to run your own UnActivated Step 0 WebBrowser.
Doing it yourself can only be completed after you have a registered license key for ActiveDeveloper, because in the ActiveDeveloper Demo - Saving and cut and paste of texts is disabled.
Before embarking on Step 1 open FileMerge on the Step0-UnActivated and Step1-MiniActivation folders and compare. This will give you an overview of the 5 lines you need to add in the apps Controller, in order to start using ActiveDeveloper Workspaces and Object Browsers to access your objects at runtime time.
That's all for a minimal Activation.
This first time, you will probably be best off using Xcode as your editor to make this simple change of Controller.m.
Because, we are now being very explicit in taking the activation in multiple steps. Later on, when you know the Activation
process, you will probably combine Step 1 and Step 2 of Activation into one Step and do it all in the ActiveDeveloper Class Editor.
Before compiling the Step 1 application we need to tell Xcode to link the static library libActiveDeveloper.a, so you can connect over the network to your application and form an ActiveDeveloper session with it.
Regarding "ZeroLink". Be aware that if you turn ZeroLink ON you only get app skeletons that you can't copy around your system or hand out to your testers. ActiveDevelopers incremental compilation of Objective-C works equally well with ZeroLink OFF ... so if you turn it OFF ... you can still both interact from ActiveDeveloper and copy your development apps around.
Notice 1): If the libActiveDeveloper.a static library is not yet in your linker path
- please read "HowTo: Install ActiveDeveloper" or do as suggested below.
Notice 2): If you get ranlib linker warnings - please read "HowTo: Install ActiveDeveloper" or do as suggested below.
(For ActiveDeveloper Demo Evaluators)
Before installing ActiveDeveloper onto your computer you can also share the common static libActiveDeveloper.a inside
the CocoaDemos project by taking a copy of your own code and put it next to the other Samples in the CocoaDemos project.
To initiate an ActiveDeveloper session you should create a *.projectimage file for your application and include this in your Xcode project.
In ActiveDeveloper, create a new projectimage file (menu "Source Editors>New Project"), you will notice the popup list blanks out. Enter the exact name of our application without app extension (WebBrowser) in the top right text box. Enter the location of the executable in the text field beside the Stop button, this path is relative to where you are going to save the projectimage file. We are going to save it in our top level Xcode folder, so the relative address is:
In ActiveDeveloper - menu "Select File>SaveAs" and choose filename AD.projectimage
Drag or add the AD.projectimage file into your Xcode project, as Project Relative.
Now you are setup for full convenience - using ActiveDeveloper and Xcode in concert.
To open a *.projectimage with ActiveDeveloper and start a session, drag the AD.projectimage file icon from Xcode to the ActiveDeveloper app icon in the Dock. Notice that WebBrowser becomes selected in the PopUp button. Press Start in ActiveDeveloper and your copy of WebBrowser Step 1 will appear.
To verify the connection ...
Create a new Workspace and type [[NSApp mainWindow] delegate]; into it's lower coding pane. Then, select the statement and click Inspect. We now have access to the runtime objects of your Step 1 WebBrowser via the Object Browser and the Workspace.
A moment to appreciate ...
Save your Workspace as f.ex. workspace.wsp in the same folder as you saved the AD.projectimage file above. Then, for easy access to it later, drag it into your Xcode project just like you did with the AD.projectimage file (see image above)
If you launch your Activated applications from Finder.app or from an Xcode launch button, they will run normally - but you won't enter into an ActiveDeveloper session. This ONLY happens when you launch your application from the ActiveDeveloper Start button.
This is very practical as soon as you start having a number of Activated projects in your environment that you use frequently. Like this you can run them both in and out of ActiveDeveloper session just as you like.
So if you launch your Step 1 WebBrowser from Xcode - you will get the following notice in the console. The WebBrowser will be running just fine - but stand alone - not connected to ActiveDeveloper.
As of Step1 you have a Minimal Activation, and you are able to connect to your application from ActiveDeveloper. You can browse around it's live object structures with the Object Browser and evaluate/display/inspect Objective-C code selections incrementally inside your running application from a Workspace or from the Object Browser.
This is very useful for Debugging your application and to learn the API's of the frameworks you use.
During Step2 of Activation we will expand to support Development also - and show how to use ActiveDeveloper as a Source Code Editor for your projects Objective-C classes and categories. The ActiveDeveloper Class Editor works even in the middle of an ActiveDeveloper session - using the "Load" button. So, you can use the ActiveDeveloper Class Editor to further develop your application - while it is still running
Runtime incremental Class Editing is very powerful ... you want to get this right.
After Step2 of Activation you can use ActiveDeveloper to both Develop and Debug your applications, and ActiveDeveloper allows you to even combine Development and Debugging into ONE single activity. The code you develop in the Class Editor can be immediately added to your running application - without having to restart it first ... cool right ...
The ActiveDeveloper Class Editor does that by allowing you to:
We will now show you how to Activate All the WebBrowser classes for incremental editing with the Class Editor in one go. This time you will be better off doing the code changes in ActiveDeveloper than in the Xcode editor (you need a registered license key to perform and save these changes yourself).
The Step 2 of this Sample is similar to Step 2 in the previous Sample - but here we Activate multiple classes. Therefore we collect the Class definitions into one single new file called Classes.[hm]. This is both to minimize the total number of files and to simplify #import'ing. The Objective-C methods that we want to edit incrementally are still split into Category files along class lines (Class+Category.[hm]).
With FileMerge you can see the difference between the previous Step1 and current Step2 (the top level folder). Be aware that differences look larger on the screenshot, because FileMerge still show the Controller.[hm] and MyDocument.[hm] class files - even though they are no longer needed in Step 2.
For both classes there are basically 2 changes made during class Activation:
Using the ActiveDeveloper Class Editor, you create a new Objective-C Class file using the
menu item (Menu: Source Editors: New Class). This gives you a fresh Class Editor window with a
template content to guide your work. Remove the Category template section (if any) and remove the
Prefix template (if any), replace CLASS in the top #import with Classes and duplicate the Class template
so you have two of them.
Using the TextEdit application you open Controller.h and MyDocument.h to use them as a pasteboards.
(Stay away from the Xcode editor for this task !!)
Now, for each class definition in the header files (2 in this case) copy the @interface line plus the following instance variable section and paste these into the @implementation file so they each replace a Class template from @implementation to right before @end. Substitute the @interface keyword in the code you pasted with an @implementation keyword. You now have 2 Objective-C @implementation declaration sections.
Then copy all the top #imports and declarations before the class @interface in both header files
and paste and merge them to the top left Prefix text pane in the ActiveDeveloper Class Editor window -
removing any template text already in there.
Then copy all the bottom declarations after the last @end in both header files and paste and merge
these after the template in the Bottom left Suffix text pane of the ActiveDeveloper Class Editor window.
You have now extracted the relevant Objective-C class information from both header files into the new class implementation file - and you don't need the header files anymore. Now save the new ActiveDeveloper class window - calling it Classes.m - and close the TextEdit header files. ActiveDeveloper will now automatically have generated you a new header file Classes.h - by extracting the relevant Objective-C information directly from your Classes.m file plus from your added Prefix and Suffix interface content. So, now you don't need to edit Objective-C header files by hand anymore ...
We will now show in detail how to do with the Controller class. Step 2c is the same for the other class MyDocument.
Using the ActiveDeveloper Class Editor, you create a new Objective-C Controller category file using the menu item (Menu: Source Editors: New Class Category). This gives you a fresh Class Editor window with a template content to guide your work. Remove the Class template section (if any), remove the Prefix and Suffix templates (if any) and keep only the Category template section and the source #imports. Substitute CLASS in the #import statement above with the new project class filename Classes.
Now, open the Controller.m file with TextEdit and select all of the Controller method implementations. Copy them out of the Controller.m file and paste them into the new Category Editor window, placing them on top of the template -method between @implementation CLASS (Category) and @end. Rename the template text CLASS to your class name (Controller) and the template text CATEGORY to your category name (Methods).
Then, save the new category Editor to file and call it Controller+Methods.m. ActiveDeveloper will now automatically generate the corresponding Objective-C header file Controller+Methods.h - including all the new method declarations.
You are now almost done and ready for runtime incremental editing of the methods in the Controller+Methods.m file. We just need to fix the #imports in the Prefix and Suffix panes a bit to make the category file splitup transparent to the rest of your applications code files.
This is done by importing the header of your new category file(s) (#import "Controller+Methods.h") on the first line of the Suffix pane of the Classes.m file from step 2a above (and only there). (Plus #import "MyDocument+Methods.h" here also when you activate that class afterwards). In the rest of your code you can now use #import "Classes.h" everywhere. That file will now first declare all your Objective-C classes and then #import all of there Category interfaces. So, nobody needs to know about the category splitup - except the responsible Classes.h file - and all files will gain the same project scope making it easier to refactor your code.
Finally, save both the Classes.m Class Editor window and the Controller+Methods.m category Editor window. Add the Classes.[hm] and Controller+Methods.[hm] files to your Xcode project as project relative. Also add the MyDocument+Methods.[hm] to your Xcode project when you have repeated this step on that class also. And you can now remove the old Controller.[hm] and MyDocument.[hm] files from your project. You can now take a look at the *.[hm] files with TextEdit, if you are interested ...
Again, it's time to sit back and consider what we have just completed.
In order to enable incremental loading and re-loading of your Controller amd Document methods we restructured both your classes to hold their methods in separate Category files Controller+Methods.[hm] and MyDocument+Methods.[hm]. And to avoid getting too many files we collected all the Class declarations into a single new file Classes.[hm]. To do this, we used the ActiveDeveloper Class and Category Editor windows.
First we copied the Objective-C interface information over to the new Classes.m source file to allow automatic header file generation. Then we moved the methods we wanted to edit incrementally over to a new category files - that also used automatic header generation. And finally we #imported Controller+Methods.h and MyDocument+Methods.[hm] in the Suffix pane of the new Classes.m editor - in order to make the splitup transparent to the rest of the code in our application - so all other code now #import "Classes.h" uniformly.
After Step2 the application is now Completely Activated - because all of the classes are Activated for editing with ActiveDeveloper. So now you will edit the Classes.m, Controller+Methods.m and MyDocument+Methods.m files with ActiveDeveloper. The Classes.h, Controller+Methods.h and MyDocument+Methods.h header files will be autogenerated from ActiveDeveloper.
Please check the Manual section on the ActiveDeveloper Class Editor (Manual 2) for a detailed description of how to use the Class Editor during a combined Development and Debugging ActiveDeveloper session.
You can now rebuild the project with Xcode, and launch into an ActiveDeveloper session by clicking the "Start" button in the ActiveDeveloper project window.
During this Sample we guided you through Activating an existing Objective-C project in two steps:
In the Minimal Activation step we started to link the ActiveDeveloper library and created an AD.projectimage file, so we could Start an ActiveDeveloper session with your application. In the All Class Activation step we continued to Activate all the classes (Controller and MyDocument) and now we are able to Develop the whole project with ActiveDeveloper at runtime in a single combined Development and Debugging activity mode.