intellij

This cookbook allows installing and configuring the IntelliJ IDEA IDE. It can
install/update the IntelliJ package, configure "workspace" (the configuration from the idea.config.path directory),
install plugins from the Plugins Repository and configure projects (artifacts, run configurations, SDKs, modules etc.).

The main purpose of this cookbook is to be used as automatic environment configuration for developers.

Every project has its own configuration which should be added to IDE in order to make it work.
Configuring the IntelliJ IDEA can take some time (there are a lot of places which you can adjust to your needs!)
and - what is worse - can be forgotten, which leads to having a hard time when there is need to create a new environment
(for example, a new person comes to the project).

Storing your project's configuration inside Chef scripts is good not only because it can configure
the whole IJ configuration for you - it can also be used as a documentation for any new person.

NOTICE: This cookbook is NOT idempotent!

One of the Chef's ideology is to create idempotent cookbooks
that will always configure the environment the same way. This is NOT the case for this cookbook.

IntelliJ is a great tool with many configurations and developers are usually customising their environments. It means that
Chef should not update all of the configuration, which would lead to losing any changes made by the developer, but instead
it should only make sure that the base configuration stays the same. This way you can always repair your environment by
running the cookbook again - it will only restore the exact configuration written in the recipe and leave your personal
changes.

Platforms

The cookbook is mainly tested on the Windows systems. It uses mainly Ruby generic functionality
(such as zipfile, nokogiri etc.) so it is highly possible that it could be used also on any other systems by simply
modifying the paths. The support for other systems will be probably soon added.

Usage

The main way of using the cookbook is to use it's LWRP resources.

Recipes

Default.rb

The [default recipe](recipes/default.rb) will only install the IntelliJ IDEA without configuring anything. It uses
following attributes:

Attribute	Default value	Description
['intellij']['recipe']['path']	C:/Program Files/JetBrains/IntelliJ	Path where the IntelliJ will be installed. If the path is not empty, the IntelliJ will be updated to specific version/edition.
['intellij']['recipe']['source']	nil	Source from which the cookbook will download the IntelliJ package. If empty, Chef will download it from the Jetbrains site.
['intellij']['recipe']['checksum']	nil	Checksum for the IntelliJ package. If you did not set the source parameter, Chef will automatically download it from the Jetbrains site.
['intellij']['recipe']['edition']	:community	Edition of the IntelliJ to be downloaded. Can be :community or :ultimate.
['intellij']['recipe']['version']	nil	Version of the IntelliJ to be downloaded. If empty, Chef will automatically use the latest version.

Resources

The main functionality of the cookbook lies within it's resources. You can use them by defining dependency for
the cookbook inside the metadata.rb file:
ruby
depends 'intellij'


Default

[Default resource](resources/default.rb) intellij is used to download/update the IntelliJ installation.

Action	Description
install	This action will install new IntelliJ package. If the path is used by the different installation, it will compare them and display warning if the versions are not the same. Default action.
delete	This action will remove the IntelliJ package from the specified path.
update	This action is mainly the same as the install action, but will update the existing installation rather than just displaying a warning message.

Property	Type	Description
path	String	Path where the IntelliJ package will be installed. Defined also as name attribute.
version	String	Version of the IntelliJ to be downloaded. If empty, Chef will automatically use the latest version.
source	String	Source from which the cookbook will download the IntelliJ package. If empty, Chef will download it from the Jetbrains site. If you are specifying your own source, please set also the checksum, version and edition parameters.
checksum	String	Checksum for the IntelliJ package. If you did not set the source parameter, Chef will automatically download it from the Jetbrains site.
edition	Symbol	Edition of the IntelliJ to be downloaded. Can be :community or :ultimate.

Example:
```ruby

Will install the IntelliJ using the Jetbrains Download site

intellij 'C:/Program Files/JetBrains/IntelliJ' do
version '2018.3.4'
edition :community
action :update
end

Will install the IntelliJ using specific source

intellij 'C:/Program Files/JetBrains/IntelliJ' do
version '2018.3.4'
source 'https://download.jetbrains.com/idea/ideaIC-2018.3.4.win.zip'
checksum 'bff5d4f07762f2582db80240cfe1e6586cf47c304a7a2c50eb672e63be98229a'
edition :community
action :update
end
```

Workspace

Normally there is one "workspace" defined for all IntelliJ projects. Default path is stored within the idea.properties
as the idea.config.path parameter. Having the same configuration for all projects not always is good (shared configuration
is for example IDEA's theme, plugins, installed SDKs etc.). If you will break this configuration, it is highly possible
that all of your projects will stop working.

Creating separated workspace is not as easy as it would seem to. IntelliJ supports changing the path for configuration by
changing the IDEA_PROPERTIES environment variable,
but the change would affect all of the projects if set globally. Unfortunately, you can not change it by setting the
-Didea.config.path parameter during the IDEA's execution as it would try to open it as a file.

As a workaround of this problem, the cookbook will create special shortcut that is changing this location only for the
specific workspace. It will be created inside path parameter - you should start the IntelliJ only from this shortcut
if you want to have your configuration loaded properly.

[Resource's configuration](resources/workspace.rb):

Action	Description
create	This action will prepare new workspace for the IntelliJ and update all configuration that's had changed. Default action.
delete	This action will remove the IntelliJ's workspace.

Property	Type	Description
path	String	Path where the workspace will be created.
intellij_path	String	Path where the IntelliJ package is installed. It is used to create the shortcut to the workspace.
default_project	String	If set, the cookbook will set the project from this path as the default one (meaning that the IntelliJ will not ask you to open project location during the first usage).
color_scheme	Symbol	Color scheme to be used. Can be :IntelliJ or :Darcula.

Example:
ruby
intellij_workspace 'C:/Test/Workspace' do
default_project 'C:/Test/Workspace/My Project'
intellij_path 'C:/Program Files/JetBrains/IntelliJ'
color_scheme :IntelliJ
action :create
end


Plugin

[This resource](resources/plugin.rb) can be used to install the plugin from the Jetbrains plugins repository.
It will use the Jetbrains API to find plugins matching the specified name. It also allows downloading the plugin from
the specific update ("version"). If the plugin is downloaded as the .zip file, it will also automatically unzip it in the
proper location, so the user will not have to do it manually.

Action	Description
install	This action will download the plugin and then install it inside the proper directory. Default action.

Property	Type	Description
name	String	Name of the plugin. Should be defined as resource's name. Has to match exactly the name displayed inside the plugins repository, otherwise Chef will raise error.
workspace	String	Path for the IntelliJ's workspace. It is used to define the proper path for the plugins installations. Can be also set up as the "global workspace" path.
source	String	If set, the cookbook download the plugins from the different source than official repository.
update	Integer	Version of the plugin to be downloaded. If empty, the cookbook will download the latest version.
edition	Symbol	Some plugins are available only for one edition. To make sure that correct plugin will be installed, you should pass the edition parameter. Can be :community or :ultimate.

Example:
ruby
intellij_plugin 'Chef integration' do
workspace 'C:/Test/Workspace'
update 57884
edition :ultimate
action :install
end


SDK

[This resource](resources/sdk.rb) can be used to install the SDK for all projects using the workspace.
Please not that not all SDK types are available in the community edition of the IntelliJ.

Action	Description
add	This action configures the SDK inside the workspace.
delete	This action will delete the SDK from the workspace.

Property	Type	Description
name	String	Name of the SDK. Should be defined as resource's name.
workspace	String	Path for the IntelliJ's workspace.
path	String	Path where the SDK is installed.
type	Symbol	Type of the SDK. Can be :JavaSDK or :RUBY_SDK. More SDK's will be added if needed.

Example:
ruby
intellij_sdk 'Ruby 2.6.1' do
workspace 'C:/Test/Workspace'
path 'C:/Program Files/Ruby26-x64'
type :RUBY_SDK
action :add
end


Project

[This resource](resources/project.rb) will create a new IntelliJ IDEA's project.

Action	Description
create	This action will create and configure the project.
delete	This action will delete the project.

Property	Type	Description
path	String	Path where the project will be created. Name attribute.
project_name	String	Optional project's name. If empty, the name of the directory will be used.
default_sdk_name	String	Optional. Name of the SDK that will be set up as default one.
default_sdk_type	Symbol	Type of the SDK. Can be :JavaSDK or :RUBY_SDK. More SDK's will be added if needed.
language_level	String	Language level of Java used within the project. Default: JDK_10.

Example:
ruby
intellij_project 'C:/Test/Workspace/My Project' do
project_name 'My fantastic project'
default_sdk_name 'Ruby 2.6.1'
default_sdk_type :RUBY_SDK
action :create
end


Module

[This resource](resources/project.rb) will create new module to the existing IntelliJ IDEA's project.
Modules are usually root directories of source codes for your applications. The resource assumes that you already have
them on the disk (either downloaded from repository or simply created before using this cookbook.).

The resource will automatically detect whether the project is Maven project. If yes, it will add it to the IJ's
Maven configuration.

It also tries to automatically detect which control version system is used (if any). Currently only
Git repositories will be detected - support for CVS and other ones will be added if needed.

Action	Description
create	This action will create and configure the module.
delete	This action will delete the module.

Property	Type	Description
path	String	Path where the module is created.
type	Symbol	Type of the module. IntelliJ has different types for different languages/frameworks. Currently possible options are: :JAVA_MODULE, :RUBY_MODULE and :WEB_MODULE. Defaults to :WEB_MODULE.
sdk_type	Symbol	Optional SDK type for this specific module. Can be :JavaSDK, :RUBY_SDK or :none.
sdk_name	String	Optional SDK name for this specific module.
module_name	String	Optional module's name. If not set, the name of the directory will be used.
project_path	String	Path where the project is created. Required.

Example:
ruby
intellij_module 'C:/Test/Workspace/My Project/Maven module' do
project_path 'C:/Test/Workspace/My Project'
type :JAVA_MODULE
module_name 'sample-maven-module'
sdk_name 'JDK 10.0'
sdk_type :JavaSDK
action :create
end


Run configuration

[This resource](resources/run_configuration.rb) can be used to define Run configurations used within the project.

Run configurations are usually stored within the .idea/workspace.xml file, inside the RunManager component.
There are many plugins which are adding new possible templates for RC, so it is almost impossible to cover
all of the types in this cookbook. Instead of making resource for every type, you should provide the configuration as XML.
When using the resource, please make sure that the configuration will be taken from the workspace.xml file.

Action	Description
create	This action will create and configure the Run Configuration.
delete	This action will delete the Run Configuration.

Property	Type	Description
name	String	Name of the Run configuration. Should be defined as resource's name.
type	String	Type for the Run configuration. Please check the workspace.xml file to get this value.
factory	String	Factory for the Run configuration. Please check the workspace.xml file to get this value.
folder	String	Optional. If set, the resource will move this configuration inside this folder.
body	String	Body of the run configuration. Please check the workspace.xml file to get this value. You should copy the XML fragment INSIDE the <configuration> element.
project_path	String	Path where the project is created. Required.

Example:
ruby
intellij_run_configuration 'Start simple batch script' do
project_path 'C:/Test/Workspace/My Project'
type 'BatchConfigurationType'
factory 'Batch'
body <<-EOH
<option name="INTERPRETER_OPTIONS" value="" />
<option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
<option name="PARENT_ENVS" value="true" />
<module name="" />
<option name="SCRIPT_NAME" value="$PROJECT_DIR$/example.bat" />
<option name="PARAMETERS" value="Hello" />
<method v="2" />
EOH
action :create
end


Artifact

[This resource](resources/artifact.rb) can be used to add an IntelliJ's artifact inside the project.
Similar to the Run configuration resource, it uses whole XML fragments to avoid making very complicated logic for all
possible types of artifacts.

Action	Description
create	This action will create and configure the artifact.
delete	This action will delete the artifact.

Property	Type	Description
artifact_name	String	Name of the artifact. Resource's name attribute.
output_path	String	Path where the artifact will be created after rebuilding sources within IntelliJ.
root	String	<root> element of the artifact. Please check the original artifact file (in ./idea/artifacts directory) to get this value.
project_path	String	Path where the project is created. Required.
type	String	The type of the artifact. Please check the original artifact file (in ./idea/artifacts directory) to get this value.

Example:
ruby
intellij_artifact 'sample-maven-module:jar' do
project_path 'C:/Test/Workspace/My Project'
type 'jar'
root <<-EOH
<root id="archive" name="sample-maven-module.jar">
<element id="module-output" name="sample-maven-module" />
</root>
EOH
action :create
end


More examples

You can find more examples of usage for every resource inside the [recipes](recipes) directory.