Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Capella/Installation Guide"

(Capella Installation)
m (Uninstallation Procedure)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Scope =
 
 
== Typographic and Notation Rules ==
 
 
To improve legibility, some text elements are identified by specific typographic rules in according to their tutorial purpose.
 
* '''Emphasis''' font is applied to emphasize words which designs controls (Click on '''Cancel''')
 
* <code>Fixed</code> font is applied to expressions and texts of ASCII (<code>C:\My documents\Path</code>)
 
* ''Terminology'' font is applied on expressions referenced in Terminology table.
 
 
== Identification ==
 
 
This document is applicable to Capella 1.0.0.
 
 
== Document Overview ==
 
 
This document is intended for persons in charge of installing Capella.
 
It describes the installation, configuration and uninstallation of Capella.
 
 
 
= Capella Installation =
 
= Capella Installation =
 +
[https://github.com/eclipse/capella/blob/master/doc/plugins/org.polarsys.capella.ui.doc/html/Installation%20Guide/How%20to%20install%20Capella%20and%20Addons.mediawiki#table-of-contents]
  
== Prerequisites Needed for Install ==
+
== Installing extensions ==
  
For successful installation of Capella, your computer must meet the following recommended system requirements:
+
Viewpoints and addons can be found on [https://www.polarsys.org/capella/addons.html Capella addons page].
* 64-Bit Windows, Linux or Mac Operating System
+
* An unzip utility such as WinZip or equivalent
+
* 2 GHz 64-Bit processor
+
* 4 GB RAM
+
* 15 GB of available hard disk space
+
  
 
+
To install these extensions, please follow this [https://github.com/eclipse/capella/blob/master/doc/plugins/org.polarsys.capella.ui.doc/html/Installation%20Guide/How%20to%20install%20Capella%20and%20Addons.mediawiki#Configuration_and_Extensibility].
From Version 5.0.0 Capella now includes and is configured to use its own Java Runtime Environment ([https://adoptopenjdk.ne AdoptOpenJDK]).
+
 
+
For Version 1.2.x to 1.4.x Capella requires Java Runtime Environment 64 bits version 1.8 update or later installed in the computer: recommended version is '''jre-8u121-windows-X64.exe''' or later.
+
 
+
== Windows Installation Procedure ==
+
 
+
Before starting installation, target location of Capella must be cleaned:
+
# Previous Capella version must be correctly uninstalled (See related section)
+
# All manual patches/extensions must be removed
+
 
+
 
+
* First, [http://polarsys.org/capella/download.html download Capella] according to your system configuration:
+
 
+
* Extract the archive file in a given directory using a compression software of your choice
+
 
+
<u>Note:</u> Capella is based on Eclipse: folder hierarchy and namespace of Capella and Eclipse plugins are quite long. Because of Windows folder path restriction, avoid entering a too long installation location. In case the path is too long, the extraction will raise an error, the location shall be deleted and extraction done again.
+
 
+
== Mac Installation Procedure ==
+
 
+
<u>Note:</u> As stated on the download page the Mac version has not been field-tested.
+
 
+
The following instructions are applicable to macOS Big Sur (11.1).
+
 
+
* First, [http://polarsys.org/capella/download.html download Capella] for Mac Cocoa.
+
 
+
* Depending on you Mac configuration you may need double click on the archive to extract or it will have extracted automatically when the download completes.
+
 
+
* Using Finder drag the Capella to you applications folder.
+
 
+
* Launch Terminal from your Applications > Utilities or using a spotlight search (CMD + Space)
+
 
+
* In the Terminal window type: <code>xattr -d com.apple.quarantine /Applications/Capella.app</code>
+
 
+
== Starting Capella ==
+
 
+
=== Windows ===
+
 
+
Capella installation is complete if the archive extraction finished without errors.
+
 
+
* Go to installation directory and check the '''capella''' directory contains two folders:
+
** '''eclipse''': the Capella modeling workbench
+
** '''samples''': the ''In-Flight Entertainment'' sample model
+
 
+
* Open the ''capella/eclipse'' directory and check the tree looks like this:
+
 
+
 
+
[[Image:Capella_0.8.3_extracted.png‎]]
+
 
+
 
+
* Run ''eclipse.exe'' to start Capella
+
* Capella should start with below splash screen.
+
 
+
 
+
 
+
{| border="1" cellpadding="6" style="border-collapse:collapse; background-color:orange;"
+
|<u>Note:</u> For Version 1.2.x to 1.4.x in case Capella does not start, edit the ''eclipse.ini'' file and add a line:
+
 
+
After:
+
 
+
<code>
+
-showsplash
+
</code>
+
 
+
<code>
+
org.polarsys.capella.core.platform.sirius.ui.perspective
+
</code>
+
 
+
skip a line and add:
+
 
+
<code>
+
-vm
+
</code>
+
 
+
<code>
+
<ABSOLUTE_PATH_TO_JAVA.EXE> (JRE/JDK 32 or 64-bits according to the version of Capella)
+
</code>
+
|}
+
 
+
 
+
 
+
At start up, Capella splash screen is displayed and shows launched version:
+
 
+
 
+
[[Image:Capella_0.8.3_splash.png‎]]
+
 
+
 
+
The following welcome view appears when a new workspace is selected. New users can use this view to easily start with Capella, or close this view to get Capella Perspective based on eclipse standard perspective.
+
 
+
 
+
[[Image:Capella_0.8.3_welcome.png‎|800px]]
+
 
+
=== Mac ===
+
 
+
Mac users after following the installation procedure above should launch Capella from Applications.
+
 
+
=== Perspective Views ===
+
 
+
Capella Perspective shall appear with below views (refer below image):
+
* Capella Project Explorer
+
* Fast Linker
+
* Properties
+
* Information
+
* Semantic Browser
+
 
+
 
+
[[Image:Capella_0.8.3_perspective.png‎|800px]]
+
 
+
 
+
<u>Note:</u> In case Capella Perspective is not started or closed by User, it can be reopened: select the menu ''Window/Open Perspective/Other.../Capella":
+
 
+
 
+
[[Image:Capella_0.8.3_open_perspective.png]]
+
 
+
 
+
=== Check Version and Build ID ===
+
 
+
Go to Capella Advance "Help/About Capella" and check that the version release number is the one installed (Build ID is also displayed):
+
 
+
 
+
[[Image:Capella_0.8.3_about.png]]
+
 
+
 
+
 
+
[[Image:Capella_0.8.3_about_build.png]]
+
 
+
 
+
=== Help/About Capella to check JRE ===
+
 
+
Go to Capella menu "Help/About Capella" then "Installation Details" then "Configuration Tab" and check that JRE path is correctly selected:
+
 
+
 
+
For Version 1.2.x to 1.4.x Capella requires Java Runtime Environment 64 bits version 1.8 update or later installed in the computer: recommended version is jre-8u121-windows-X64.exe or later.
+
 
+
== Installing sample models==
+
 
+
Sample models can be found on [https://www.polarsys.org/capella/download.html Capella download page].
+
 
+
To install these models, please follow this procedure:
+
* Download a sample (zip file)
+
* In Capella, click on "File > Import"
+
* Select "Existing Projects into Workspace" and click on "Next"
+
* Select "Select archive file" and click on "Browse..."
+
* Select the downloaded zip file
+
* Click on "Finish"
+
 
+
=== Verification ===
+
A new project in your workspace should have been created.
+
It contains a aird file. Double-click on it to open the Capella editor showing the workflow.
+
 
+
== Installing extensions==
+
 
+
Viewpoints and addons can be found on [https://www.polarsys.org/capella/download.html Capella download page].
+
 
+
To install these extensions, please follow this [https://wiki.polarsys.org/Capella/Extensions/Installation_Guide#Installation_Procedures procedure].
+
 
+
= External Viewpoints Management =
+
 
+
Capella enforces the presence of all external Viewpoints used by a project to avoid probable data loss. It is mandatory to install all these Viewpoints in Capella in order to migrate or to open a project.
+
 
+
If these Viewpoints are not available or installed in the Capella target version, a preparation of the project is needed before the migration/opening will be possible.
+
 
+
A specific tooling is dedicated to this preparation, please read related documentation at Kitalpha [https://polarsys.org/wiki/Kitalpha wiki] ('''Detachment'''): this tooling is packaged in Kitalpha directly, which means by default available in Capella. Moreover files must be '''writable''', so that detach can update and backup successfully
+
  
 
= Migration of an Existing Project =
 
= Migration of an Existing Project =
 
+
[https://github.com/eclipse/capella/blob/master/doc/plugins/org.polarsys.capella.ui.doc/html/First%20steps%20with%20Capella/3.5.%20How%20to%20migrate%20Capella%20projects.mediawiki]
== Overview ==
+
 
+
What is performed in a global project migration?
+
 
+
# The tool locates all .melodymodeller files at the root of the Eclipse project and migrate them (including all fragments located in the /fragment folder)
+
# The tool locates all .aird files at the root of the Eclipse project and migrate them (including all fragments located in the /fragment folder)
+
# The tool locates all .pattern files at the root of the Eclipse project and migrate them
+
# The tool perform a Sirius Migration on all aird files (including fragments)
+
 
+
== Note for External Viewpoints ==
+
 
+
In case your model deals with external Viewpoints, please read previous section "External Viewpoints management".
+
 
+
== Prerequisites ==
+
 
+
* All the open sessions (aird) of the workspace must be closed.
+
* When working with ClearCase or SVN, all project files must be previously checked-out
+
* Apply Viewpoint Refresh preferences ( Enable ''Do refresh on representation opening'' and ''Automatic Refresh'' )
+
* All used extensions must be installed (e.g.: Basic Variability, etc.)
+
 
+
== Recommendations ==
+
It is highly recommended to baseline in source control the whole Capella Projects/artefacts/links (or a make a full backup of the files), before running migration process.  
+
 
+
== Configuration ==
+
For optimized memory management, especially with medium to large size models,
+
* It is better to perform the migration right after a fresh start of Capella
+
* It is better to restart Capella after the migration has completed
+
 
+
Enough disk space is required to launch Capella migration because of backup files and Eclipse configuration files. In case of migration failure, please check disk free space.
+
 
+
With big models, it might be necessary to increase the RAM allocated to Capella . To do so, create a Windows shortcut towards '''eclipse.exe''' in the Capella  installation folder. Open the shortcut properties, and replace the target field by the following:
+
 
+
{| border="1" cellpadding="15" cellspacing="0" style="border-collapse:collapse;"
+
|<code>
+
CAPELLA_HOME\eclipse.exe  -clean -vmargs -Xms768m -Xmx768m -XX:PermSize=256m -XX:MaxPermSize=256m -XX:+CMSPermGenSweepingEnabled -XX:+CMSClassUnloadingEnabled
+
</code>
+
|}
+
 
+
Or in some cases:
+
 
+
{| border="1" cellpadding="15" cellspacing="0" style="border-collapse:collapse;"
+
|<code>
+
CAPELLA_HOME\eclipse.exe  -clean -vmargs  -Xms128m -Xmx1550m -XX:MaxPermSize=100M -XX:+CMSPermGenSweepingEnabled -XX:+CMSClassUnloadingEnabled
+
</code>
+
|}
+
 
+
== Procedure while using Libraries ==
+
'''Follow below procedure if migration is required for Capella project referencing library project'''
+
 
+
<u>Consider an example as below:</u>
+
* MelodyProject01 -> (reference) LibraryProjectSub01 & LibraryProjectSub02
+
* LibraryProjectSub01  ->(reference) LibraryProjectSuper01 & LibraryProjectSuper02
+
 
+
<u>Migration Procedure of above projects: </u>
+
Migrate Projects in following sequence:
+
# LibraryProjectSuper01
+
# LibraryProjectSuper02
+
# LibraryProjectSub01
+
# LibraryProjectSub02
+
# MelodyProject01
+
 
+
== Launch the Migration ==
+
 
+
<u>Note:</u> Project Migration has been enhanced: "Refresh all Representations" and "Fix filters on all Representations" are not required for migration process. However, they are still available to repair / re-synchronize diagrams in the project life.
+
 
+
Capella project migration is run globally. To do so, use the contextual menu available on the Eclipse project containing the model.
+
 
+
A reminder asks to manually make a versioned copy (baseline) of the model before running migration.
+
Capella creates backup files before performing migration to go back in case of migration problems, even if models are not managed in source control. Please check the option ''Backup models before the migration''.
+
 
+
A dialog shows the progress. The model may be opened automatically several times by the migration.
+
 
+
<u>Notes:</u>
+
* Migration process has been enhanced for more performances.
+
* Do not try to interfere here, even though it takes a moment before the UI shows a dialog.
+
 
+
 
+
[[Image:Capella_0.8.3_migration_job.png]]
+
 
+
 
+
The result is the following. The ".old" files can be deleted if everything went ok.
+
 
+
Open the model as usual to check everything is fine.
+
 
+
 
+
[[Image:Capella_0.8.3_migration_result.png]]
+
 
+
 
+
<u>Reminder:</u>
+
* For big models, it is recommended to close Capella and restart it if necessary
+
* It is recommended to check-in, then baseline, all files closing Capella and restarting it before starting working.
+
 
+
= Optional Commands =
+
 
+
== "Refresh all Representations" Command ==
+
 
+
Open model session, right click on aird file and select contextual menu "Refresh all Representations":
+
 
+
 
+
[[Image:Capella_0.8.3_refresh_representations.png]]
+
 
+
 
+
[[Image:Capella_0.8.3_refresh_update.png]]
+
 
+
 
+
[[Image:Capella_0.8.3_refresh_job.png]]
+
 
+
 
+
Some diagrams are updated with semantic Capella updates:
+
 
+
 
+
[[Image:Capella_0.8.3_refresh_sbrowser.png]]
+
 
+
 
+
'''Save''' the model.
+
 
+
== "Fix Filters on all Representations" Command ==
+
 
+
''In contruction''...
+
 
+
== Additional Information ==
+
 
+
Capella version ''Vi'' ensures project migration for a model done on version ''V(i-1)'' (or V(i-j) in case of no modification made on metamodel and diagram analysis specification).
+
 
+
So, before installing latest Capella version Vi, all project shall be migrated in each intermediate version.
+
 
+
For instance, in case new delivered release is V1.1, for a project made previously with Capella V0.8.3, end user shall:
+
* First, install Capella intermediate version V1.0 for instance and run migration process to migrate project from V0.8.3 towards V1.0
+
* Then, install latest release (i.e. V1.1) and run migration process to migrate project from V1.0 towards V1.1
+
 
+
<u>Note:</u> It is possible to check the current version of a model, right clicking on the .melodymodeller file.
+
  
 
= Uninstallation Procedure =
 
= Uninstallation Procedure =
 
+
[https://github.com/eclipse/capella/blob/master/doc/plugins/org.polarsys.capella.ui.doc/html/Installation%20Guide/How%20to%20install%20Capella%20and%20Addons.mediawiki]
To uninstall Capella:  
+
* Check there is no useful remaining workspace in Capella installation directory
+
* Remove the Capella installation directory
+

Latest revision as of 08:34, 4 February 2021

Capella Installation

[1]

Installing extensions

Viewpoints and addons can be found on Capella addons page.

To install these extensions, please follow this [2].

Migration of an Existing Project

[3]

Uninstallation Procedure

[4]

Back to the top