AppCode Quick Start Guide

Step 0. Before you start

Here's a short FAQ before you start.

  1. Do I need Xcode at all?
    Yes, you do. AppCode will not run without Xcode available.
  2. Which version of Xcode should be installed?
    AppCode 3.3 officially supports Xcode 6.4 or higher on OS X 10.10. For OS X 10.11 please use Xcode 7/7.1.
  3. Can I use both AppCode and Xcode at the same time?
    Yes, you can use both simultaneously. Changes will be synced.
  4. Is AppCode OS X only?
    Yes, AppCode needs Xcode, Xcode runs on OS X. Minimum supported version is OS X 10.9.
  5. 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 let’s get started!

to the top

Step 1. Open/Create a project in AppCode

Welcome to JetBrains AppCode!

Let’s 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.

AppCode is fully compatible with Xcode: it uses the same project model and project file, and synchronizes all changes with Xcode. You can work simultaneously in both IDEs, make changes and jump back and forth - AppCode will make sure that everything is synchronized and up to date.
Welcome to JetBrains AppCode

If you prefer to start from scratch, click New Project on Welcome screen.

AppCode supports all Xcode templates, so you can start new projects the same way as in Xcode.
AppCode new Xcode Project

to the top

Step 2. Look around

So you’ve opened a project in AppCode for the first time, now, before we move on let’s take a moment to get familiar with the key UI elements you will encounter here at one point or another.

UI Components

  1. 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.
  2. Smart code editor on the right side has tabs for easy navigation between open files.
  3. Navigation bar above the editor additionally allows to quickly run, debug, test or profile your application.
  4. 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.
  5. 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.
  6. 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.

to the top

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. That’s what we’re going to do now - let’s make the ride enjoyable.

IDE look

First thing to tune is the general “look and feel”. You can find related settings under Preferences | Appearance & Behaviour | Appearance.

IDE Appearance


Quick switch theme Switch Keymap

The Preferenes | Editor section contains a number of pages that will help you to customize every aspect of the editor’s 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+`.

to the top

Step 4. Find your way through

With a project’s growth and when you work with someone else’s code, it’s 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.

To jump to a function, method, a macro definition or any other symbol - hit Alt+Cmd+O (Navigate To Symbol).
Navigate to class

When you explore a project’s source code, it’s often important to know where this or that symbol is actually used. To find that out, place the caret at the symbol’s 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.

Find usages

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.

Cmd+B to jump to declaration, Cmd+U to navigate to super definition.

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 that’ll help you to navigate through the hierarchy.

to the top

Step 5. Generate some code

New class

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.

Once you’re familiar with Live Templates, you can even create your own under Preferences | Editor | Live Templates.

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.

to the top

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.

Code Completion

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 you’re currently working in and suggests the list of choices accordingly. It filters the list of methods and variables to match the expression type.


Intention Actions

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 there’s a method that needs to be declared, a property to be generated, a string that has to be localized, you’ll see a light bulb in the left gutter area - hit Alt+Enter to see the suggested intention.

Declare method in interface

to the top

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, you’ll see a light bulb in the left gutter. Click on it, or hit Alt+Enter to apply a fix.

You can also run code analysis in a bulk mode to see all potential problems in your project and fix them at once. To do so, choose Code | Inspect Code from the main menu.
Code inspection

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.

to the top

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.

Rename safely

Rename even works across non-code usages like xib, storyboard files and localization files.

One of the most important refactorings is Rename, and you’d want to be sure all the changes it does are safe. Not to worry - that’s 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.

Refactor This

Refactor this

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.

to the top

Step 9. Run and debug your app

Run configurations in AppCode reflect Xcode schemes, and synchronize with them. Notice, that run and debug in AppCode are two different actions. Sometimes you might want just to run your app without stopping at breakpoints, and and try it the same way it will be used by your users.

Now, when you’ve played with the code and discovered what you can do with it, it’s 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.

AppCode’s 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 don’t waste your time, but actually investigate the problem.

You can also evaluate any arbitrary expression with Evaluate feature - it show the result in the same structural representation and you can dig into it right in the result view.

to the top

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.

Run tests

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.

Test runner

to the top

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 you’ve 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 you’ve 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.

Local History

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.

Local history

to the top

That’s 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!

The full documentation is available in our Online Help. If you have any additional questions, you're welcome to post them on the AppCode Discussion Forum and to read our blog from time to time.

to the top