AppCode Quick Start Guide
Step 0. Before you start
Here's a short FAQ before you start.
Do I need Xcode at all?
Yes, you do. AppCode will not run without Xcode available.
Which version of Xcode should be installed?
AppCode 3.1 requires Xcode 6.1 or higher.
Can I use both AppCode and Xcode at the same time?
Yes, you can use both simultaneously. Changes will be synced.
Is AppCode OS X only?
Yes, AppCode needs Xcode, Xcode runs on OS X. Minimum supported version is OS X 10.9.
Will I be able to work with my project in Xcode after I edit it in AppCode?
Yes, AppCode uses the same project model as Xcode.
Now lets get started!
Step 1. Open/Create a project in AppCode
Welcome to JetBrains AppCode!
Lets begin by opening one of your existing projects. You can do this right from the Welcome screen, just click Open Project, and locate the xcodeproj or xcworkspace file.
If you prefer to start from scratch, click New Project on Welcome screen.
Step 2. Look around
So youve opened a project in AppCode for the first time, now, before we move on lets take a moment to get familiar with the key UI elements you will encounter here at one point or another.
Switch to File View to browse the physical layout of your project files and directories rather than the logical structure.Project view on the left side presents your project in a familiar way, like Xcode does.
- Smart code editor on the right side has tabs for easy navigation between open files.
- Navigation bar above the editor additionally allows to quickly run, debug, test or profile your application.
It also shows line numbers and per-line VCS history.Left gutter: this vertical stripe next to the editor shows the breakpoints you have, and provides a convenient way to navigate through the code hierarchy like going to definition, subclass, superclass, etc.
The square in the right corner shows the overall status of code analysis for the file.Right gutter: AppCode constantly tracks the quality of your code, and you can see the results of code analysis instantly in the right gutter: errors, warnings, etc.
- Tool window: specialized secondary windows that are attached to the bottom and sides of the workspace and provide access to typical tasks such as project management, source code search and navigation, running and debugging, integration with version control systems, etc.
Step 3. Customize your environment
Working in IDE is like driving a car, before you can comfortably get going, you need to adjust mirrors and seats, locate the important switches, etc. Thats what were going to do now - lets make the ride enjoyable.
First thing to tune is the general look and feel. You can find related settings under Preferences | Appearance & Behaviour | Appearance.
The Preferenes | Editor section contains a number of pages that will help you to customize every aspect of the editors behavior. There are two different looks for the whole IDE, however there are more themes available just for the editor including Xcode theme. You can quickly switch color scheme, keymap, code style scheme or look and feel right from the editor by pressing Ctrl+`.
Step 4. Find your way through
With a projects growth and when you work with someone elses code, its vital to be able to quickly find the elements of interest, and dig into the code. AppCode comes with a set of navigation features that will help you find your way through any code no matter how tangled it is.
The first thing you probably will want to do is open a class or file in the editor. Just hit Cmd+O (Navigate To Class) or Shift+Cmd+O (Navigate To File), and type in the name. The name is too long? Just type the upper case letters from it - AppCode will find the matches. Remember only part of the name? No problem - enter what you remember.
When you explore a projects source code, its often important to know where this or that symbol is actually used. To find that out, place the caret at the symbols name and hit Alt+F7.
AppCode will find the actual usages, not just text matches. Moreover, it understands and can be used with localization, Core Data and xib files.
For documentation just press F1. AppCode also supports two external documentation browsers - Dash and Ingredients which you can enable at Preferences | Editor | External Documentation.
Quick Definition (Alt+Space) will help you to see the contents of a method without jumping to it. Hit Cmd+P (Parameter Info) to see the list of parameters this method can take.
A number of features will help you explore your code hierarchy and structure. There are dedicated views available from Navigate menu, such as File Structure, Imports Hierarchy, Method Hierarchy, even Call Hierarchy, special shortcuts to navigate between implementation, super and children (Alt+Cmd+B), and for those who prefer using mouse - little icons in the left gutter area thatll help you to navigate through the hierarchy.
Step 5. Generate some code
Adding new classes, protocols, categories, files from Xcode templates, etc. in AppCode is a snap: select File | New... from the main menu, or press Cmd+N. Select an element from the list and enter its name.
AppCode comes with wide set of code generation options. Need a loop, an NSLog call, property declaration? Use Live Templates - the alternative to Xcode snippets. Type the acronym and press Tab. There are also so-called Surround With templates available with Alt+Cmd+T shortcut: select a block of code and hit Alt+Cmd+T to surround it with a if/else, @try/@catch, @autoreleasepool, or our own construct, that can be defined under Preferences | Editor | Live Templates.
A number of various code generation options you can find under Code in the main menu:
- Override/Implement methods (Ctrl+O/Ctrl+I) - allows to override/implement any method with a single shortcut.
- Declare members - Declare members in an interface, private category or leave them in implementation in a second without the need to navigate anywhere.
- Generate (Cmd+N) - A powerful code generation tool allowing automatic creation of numerous constructs, e.g. -initWith methods, -isEqual: and -hash, accessor methods, etc.
Step 6. Code with smart assistance
AppCode stands out with its smart coding features. Whatever you develop, they are always at hand helping you to create error-free applications with no time wasted.
At every stage of development, in any files code completion is a great time saver. AppCode has two types of code completion: basic (Ctrl+Space) and smart (Ctrl+Shift+Space). While basic completion works as you type and completes any name instantly, smart completion analyzes the context youre currently working in and suggests the list of choices accordingly. It filters the list of methods and variables to match the expression type.
AppCode unties your hands and lets you develop as fast as you think, not as fast as you type. Say, you need a method. Just start using it, and AppCode will create it for you. Whether theres a method that needs to be declared, a property to be generated, a string that has to be localized, youll see a light bulb in the left gutter area - hit Alt+Enter to see the suggested intention.
Step 7. Keep your code neat
AppCode constantly tracks the quality of your code, detects potential errors and problems and suggests quick fixes for them.
Every time it finds a potential problem, like unused code, unresolved method, non-localized string or even invalid parameter in a function, youll see a light bulb in the left gutter. Click on it, or hit Alt+Enter to apply a fix.
The complete list of available inspections is available under Preferences | Editor | Inspections. You can disable some of them, or enable others, plus you can adjust the severity of each inspection. You decide whether it should be considered an error or just a warning.
Step 8. Refactor
It is important to be able to easily improve code design as it evolves with time. One of the features that distinguishes AppCode is its refactoring abilities: always at hand, safe and accurate. These are refactorings you can truly rely on. Among them you can find such vital ones as Rename, Move, Extract, Inline, Change Signature, Pull Members Up, Push Members Down, and many others.
One of the most important refactorings is Rename, and youd want to be sure all the changes it does are safe. Not to worry - thats exactly how it is in AppCode. Just place a caret at any element - variable, class, method, property, you name it - and press Shift+F6.
To quickly move code around in a full swing of refactoring, it comes in handy to inline some variable, or to extract an expression to a variable. You can even extract a full code block into a new method, and add a parameter to it using Introduce Parameter refactoring.
At any moment you need a refactoring, just press Ctrl+T to see what refactorings are suitable for the current context. Note the new Move refactoring: it allows you to move any class or member, or even a top level element, say a namespace through your project. Not only will AppCode move an element, but it will update the references, automatically manage imports and escalate visibility if needed.
Step 9. Run and debug your app
Now, when youve played with the code and discovered what you can do with it, its time to run your app. In AppCode this is done by means of so called Run/Debug Configurations. Open Run | Edit Configurations to see all available options.
To run your app, press Ctrl+Alt+R and choose a configuration. To debug your app, hit Ctrl+Alt+D.
AppCodes debugger offers the perfect runtime view of the program. Once you stop on a breakpoint, it shows descriptions of all the variables available and even content of collections and dictionaries. So you dont waste your time, but actually investigate the problem.
Step 10. Create and run tests
We all know the importance of writing tests, it goes without saying. If you enjoy test-driven development, AppCode is just the right tool to use as it completely supports OCUnit and Kiwi testing frameworks out of the box.
To create a test go to File | New | File from Xcode template and AppCode will generate a standard OCUnit test for you from template. You can also create your own template for a test, or for any other file under Preferences | Editor | File and Code Templates.
In AppCode you can run all tests at once, or a single test, you can create different test configurations to suit better your needs: in a Run Configuration just specify a test target. To run any test configuration, just invoke the Run popup (Ctrl+Alt+R) and select the one you need.
The test runner will display the test results in the dedicated Test view where you can explore them, navigate to the problems, see the test running statistics, and if needed re-run a failing test. No need to re-run them all.
Step 11. Commit and in-between
Finally, when the work is done, you can commit your changes to the preferred version control system, and you have a wide choice here: Git (or GitHub), Mercurial, Perforce, TFS, Subversion, even CVS.
To set up connection to your version control, you need to open Preferences | Version Control and specify the required credentials, and adjust additional settings that vary from one source control to another.
You can see the changes youve made, commit them, create changelists and much more from the Changes view (Cmd+9): VCS | Show Changes View.
Note, that from here you can use the difference view to see what exactly was modified. If youve been working on several different tasks, you can split your changes into a few changelists and commit them separately. That can be useful when some of your modifications still need a bit of polishing.
There are times when source control cannot help you - it only tracks differences between committed versions, while local changes can slip unnoticed. Sometimes a disaster happens, and to help you recover from it AppCode has Local History that constantly saves your changes. To view local history for a file or a folder, bring the Local History from VCS | Local History | Show History. Here you can review the changes, revert them or create a patch.
Thats it! Develop with pleasure!
Here is a very concise overview of some vital AppCode features, just to give you a quick start. There are numerous important features that can help make your life easier as a developer and your source code nicer and cleaner. Try this basic functionality and then, when you're ready, dig deeper. Enjoy developing with AppCode!