Creating a project

Now that we have the most important IntelliJ IDEA project concepts explained, we can create or import the project. Let's start with the creating a completely new project.

Creating a new project from scratch

To create the new project, select New Project form the File menu or use the standard Alt shortcuts for operation on menus: Alt + F, Alt + N, and then press Enter. You will be presented with the New Project wizard window, as shown in the following screenshot:

In the New Project wizard window, choose the technology you would like to develop with. Depending on the selected option, the dialog will change to allow you to enter settings that are more specific. For Java projects, for example, you will be able to select the framework you would like to be included in the project. Any framework needs a library of classes—IntelliJ IDEA can reuse the existing library or automatically download the proper library from the Internet. The newest version of the library is selected by default, but you can change this using the Configure button.

Tip

If you cannot see your preferred language or framework in the New Project dialog box, refer to the Pick your plugins section in the previous chapter to find the plugin for the language and framework of your choice.

When you select Maven as a starting point for your project, you can also pick the Maven archetype IntelliJ IDEA will use as the project base. This is shown in the following screenshot:

The next few windows of the New Project wizard will vary according to the option selected at the beginning. It will be the selection of SDK for Java, Scala, Ruby, and Python projects or other framework-specific options.

The last page of the wizard allows you to set paths for the project and, optionally, the project format, module location, and module name.

If the project you are creating is the first one, you will probably need to set up the SDK for the project. Click on the New button in the Project SDK section and point to the home directory of your JDK, as shown in the following screenshot:

The first three buttons in the file chooser section of the toolbar are Home Directory, Desktop Directory, and Project Directory.

You can use them as quick shortcuts to get straight to the desired directory. They are very handy and appear in every file selection dialog of IntelliJ IDEA.

When you click on Finish, in almost all of the cases, IntelliJ IDEA will create a project containing a module. We talked about modules earlier in the Modules section of this chapter.

Importing the existing project

The existing project can be imported into the IDE in two ways: from the existing sources or from the build model (it can be Maven or Gradle, for example). You can also import the Eclipse project into IntelliJ IDEA. For NetBeans, currently there is no such functionality in the IDE. However, if you would like to import the NetBeans project, you can create a new project with the existing sources.

To start the import process, click on Import project from the File menu. In the next dialog, choose the existing directory or the build file (pom.xml or build.gradle), as shown in the following screenshot:

Selecting the directory or the model to import

For Maven projects, you can also use the Open option from the File menu and then point to the pom.xml file of your project. The IDE will then import the project automatically without any additional import dialogs to fill out. Basically, IntelliJ IDEA treats Maven-based projects as first-class citizens, equal to its own project format.

If you decide to import a project from the existing Maven model, IntelliJ IDEA will create the project configuration matching the pom structure; project modules will be shaped from the pom modules and dependencies defined in the pom file will be set up as project or module libraries. The Maven output directory, target, will be excluded automatically by default. If you leave Use Maven output directories checked, IntelliJ IDEA will reuse Maven output directories as the compiler output—target or classes by default.

When you create project from the existing sources, IntelliJ IDEA will not copy the files anywhere. It will just create project in the directory of your choice; the existing sources will stay where they are.

It's good to have the Automatically download Sources and Documentation option checked; IntelliJ IDEA will try to download the library sources and API documentation to assist you better in the editor. The option can be seen in the following screenshot:

Tip

When you select Import Maven projects automatically, changes in the pom.xml file get automatically synchronized with the IntelliJ IDEA's project structure each time your pom.xml file is changed. It should be noted that when working with large projects, this synchronization can take a while. I suggest that you should disable this option when you are working on such projects.

If you choose to import the project from the existing sources, select the directory containing your project and then select the Create project from existing sources option, as shown in the following screenshot:

First, IntelliJ IDEA will scan the directory recursively for source files and libraries. The next scan will look for files specific to any known frameworks; IntelliJ IDEA will try to generate the facets if any of such file is found. Review these findings carefully; IntelliJ IDEA will try to form the project structure from them.

Then, open Project Structure from the File menu and review the generated project structure again. Look for the proper modules, libraries, and facets definitions. You can always tweak the project structure here. Feel free to modify it: add or remove modules, mark the folders with proper type, or set up the facets.

Project format

IntelliJ IDEA can store project configuration files in two alternative formats. The first one is directory-based—it is newer, recommended, and the default. The second format is file-based. You can choose the desired format in the project setup or project import wizard.

The directory-based format

When you choose a directory-based format, IntelliJ IDEA will create the .idea directory in your project folder. This directory will contain all project-wide configuration settings in a number of XML files. Specific settings are grouped in different files: compiler.xml will contain the compiler settings, modules.xml will contain the module setup, and so on.

Tip

You can throw files from the .idea folder or even the whole .idea folder into the version control system if you like with the exception of workspace.xml and tasks.xml. These files hold your personal settings, such as the tasks list, the list of opened files, local history, version control setup, and the running configurations. If you are using Maven, it's better to just throw the pom.xml file into the version control system and let IntelliJ IDEA do the rest.

The file-based format

If you decide to set up the project using a file-based format, IntelliJ IDEA will create two project files for you with the extensions .ipr and .iws. The first one, .ipr file, will contain project-specific settings. On the other hand, the .iws file will contain your personal settings, similar to the workspace.xml in the directory-based setup. IntelliJ IDEA will automatically put the .iws file on the ignore list of your version control system.

Tip

You should not put the .iws file into the version control system.

Later on, if you decide that you want to switch to the directory-based format, use the Save as Directory-Based Format option from the File menu. IntelliJ IDEA will convert your project files and reopen the project. After the project reopens, you are safe to delete the .ipr and .iws files.

The directory-based format versus the file-based format

The rationale behind the new directory-based format was to reduce merge conflicts that occurred a lot more with the file-based format. Since the settings are spread over a dozen files instead of being located in a single file, the chances of merge conflicts are somewhat reduced. The features of the directory-based format are as follows:

• You can decide what group of settings you want to share with your team using the version control system; just put the file you do not want to share in the ignore list.
• It is easier to find specific settings; the files are small and have meaningful filenames.
• IntelliJ IDEA will recognize the directory containing the .idea subdirectory as a project in the File dialog box. You do not need to select the .ipr file manually.

I believe there is no reason to use file-based configuration anymore. So let's stick to the directory-based configuration.