Difference between revisions of "Scripting environment setup"

Latest revision as of 07:52, 6 September 2021

Integrated Development Environments (IDE) like Eclipse or Idea make it much easier to edit Groovy scripts for Freeplane as in a normal text editor. Syntax highlighting, code completion, error detection, debugging and source navigation are extremely useful especially if you are not that experienced.

But it's more or less difficult for beginners to setup an IDE properly for Groovy scripting, so here's a step-by-step guide. If you have done that already you can skip to page Edit scripts in Eclipse.

Installations

First download and install a Java Development Kit (JDK) -if you don't have it. There is a hyperlink on the Eclipse download page.
Then download and install a "Eclipse IDE for Java Developers" or "Eclipse for RCP and RAP Developers" (the latter is more useful for regular Freeplane developers) from Eclipse download page. Read how to unpack here (N.B. for Windows 7 it is not possible to unpack directly into c:/Program Files; no warning is given !)
Launch Eclipse for the first time and select some directory as your workspace root

Groovy-Eclipse plugin. (Select at least "Groovy-Eclipse". - "Groovy Eclipse SDK" and "Extra Groovy Compilers" won't hurt.)
Close Eclipse

Setup workspace

Install freeplane_src

This is for installing freeplane_src for the first time. For updating it, read How to upgrade freeplane_src version.

Download the current Freeplane source distribution (e.g. freeplane_src-1.2.13.tar.gz) and unpack it into the selected workspace. Unpacking this archive may require an additional program like 7zip, jzip or winzip on Windows (check by trying to open the file in the Explorer). Unpacking may need two steps:

In a program like 7zip open the archive freeplane_src-1.2.13.tar.gz. Most unpackers will allow directly extract into a directory, but jzip creates an intermediate freeplane_src-1.2.13.tar file
Rename freeplane-1.2.13 into freeplane_src and make sure this directory is in the workspace.

On the command line (Linux/Unix/Mac, Windows 10 now also supports tar but use rename instead of mv):

   cd <workspace> # your selected workspace, like ~/freeplanescripts
   tar -xzvf freeplane_src-1.2.13.tar.gz
   mv freeplane-1.2.13 freeplane_src

For Freeplane >= 1.5 you need to create a gradle build:

You need at least gradle 2.x (install a gradle binary distribution if you need to)
Create a full gradle build by issuing the following command in the freeplane_src directory:

 $ gradle clean build cleanEclipse eclipse

Alternatively you can use the Eclipse Plug-ins for Gradle.

For Freeplane < 1.5 you do not have to perform a build.

Install groovy support

Freeplane's regular script directory <freeplaneuserdir>/scripts will be the script project directory where script development happens. To add special support for Freeplane scripting you have to copy the file freeplane_bin/scripts/freeplane.dsld to the script directory. On the command line (assuming that ~/.freeplane/1.2.x/scripts is Freeplane's script directory; Linux/Unix/Mac):

   cd <workspace> # your selected workspace, like ~/freeplanescripts
   cp ./freeplane_bin/scripts/freeplane.dsld ~/.freeplane/1.2.x/scripts

Create projects

Import the Freeplane project(s)

The Freeplane sources in freeplane_src consist of multiple projects, which are prepared for Eclipse. We can simply import this projects into our Eclipse workspace:

1. Select File->Import...

2. Set the root directory to <workspace>/freeplane_src and select all projects except freeplane-ant and (unless this happens on a Mac) freeplane-mac. Then click "Finish".

Create a Groovy project for the scripts

(You may have to click on "Other..." to see "Groovy project" option.)

2. Set the project name to "scripts", uncheck "Use default location" and enter the full path to the freeplane scripts folder (<freeplaneuserdir>/scripts):

3. Connect the scripts with Freeplane.

4. Select a different build output folder. Otherwise a lot of .class files would pollute the scripts directory. This step is not required but helpful.

Done. You can proceed now with page Edit scripts in Eclipse.

How to upgrade freeplane_src version

In case you want to upgrade your environment to a newer freeplane_src you can remove the old version first with the following steps:

Right-click on your project(s) and choose Build Path > Configure Build Path... and then the Projects tab
On this tab: select all Freeplane (source) projects, click Remove and then OK
Close your project(s)
Select all Freeplane (source) projects, press delete and then OK
Go to your freeplane_src directory and delete all files
Now you can install freeplane_src for the new Freeplane version and import the Freeplane projects or use the steps for the Eclipse Plug-ins for Gradle
Open your project(s)
Right-click on your project(s) and choose Build Path > Configure Build Path... and then the Projects tab
On this tab: click Add, add the Freeplane projects and click OK twice

Removing (step 1 and 2) and adding (step 8 and 9) the Freeplane projects to your build path are a foolproof way to ensure that your build path stays correct. You can skip them, but be sure to check if your build path is still correct because names and number of Freeplane project tend to change from time to time.

How to set up your environment with the Eclipse Plug-ins for Gradle

This is an alternative for the steps in install freeplane_src and import the Freeplane projects

Precondition

You have "Buildship: Eclipse Plug-ins for Gradle" installed in Eclipse. It is probably already included with your Eclipse if you installed one of the newer versions.

Steps

Download freeplane_src-x.x.x.tar.gz
Extract to your Eclipse workspace: tar -xvzf <downloads>/freeplane_src-x.x.x.tar.gz -C <workspace>
Rename directory freeplane-x.x.x to freeplane_root: rename freeplane-x.x.x freeplane_root (use mv for Linux/Unix/Mac)
In Eclipse click/select Run > Run configurations
Right click Gradle Task and choose New Configuration
Rename 'New_configuration' to 'Build Freeplane'
In Gradle Tasks add: clean, build and dist (so 3 tasks on 3 separate lines)
Click/select File System... > <workspace>/freeplane_root > OK
Click Run and wait till Gradle build has finished
Click/select File > Import > Existing Gradle Project > Next > Next
Specify the path to the <workspace>/freeplane_root directory in 'Project root directory' and click Finish. All projects are now imported as Gradle projects
Delete freeplane_ant (and freeplane_mac if you ar not on Mac)

Steps 4 to 9 are necessary to prevent an error in freeplane_plugin_jsyntaxpane: it needs to be built before it can be imported. It also prepares for running Freeplane from within Eclipse for Debugging scripts

@@ Line 1: / Line 1: @@
-Modern Integrated Development Environments like [http://www.eclipse.org Eclipse] or [http://www.jetbrains.com/idea/ Idea] make it much easier to edit Groovy scripts for Freeplane as in a normal text editor. Syntax highlighting, code completion, error detection, debugging and source navigation are extremely useful especially if you are not that experienced.
+Integrated Development Environments (IDE) like [http://www.eclipse.org Eclipse] or [http://www.jetbrains.com/idea/ Idea] make it much easier to edit Groovy scripts for Freeplane as in a normal text editor. Syntax highlighting, code completion, error detection, debugging and source navigation are extremely useful especially if you are not that experienced.
-But it's more or less difficult for beginners to setup an IDE properly for Groovy scripting, so here's a step-by-step guide:
+But it's more or less difficult for beginners to setup an IDE properly for Groovy scripting, so here's a step-by-step guide. If you have done that already you can skip to page [[Edit scripts in Eclipse]].
 ==Installations==
@@ Line 9: / Line 9: @@
 * Launch Eclipse for the first time and select some directory as your workspace root
 [[File:Eclipse-select-workspace.png|450px|border]]
-* [http://groovy.codehaus.org/Eclipse+Plugin Install the Groovy-Eclipse plugin].
+* [https://github.com/groovy/groovy-eclipse/wiki Groovy-Eclipse plugin]. (Select at least "Groovy-Eclipse". - "Groovy Eclipse SDK" and "Extra Groovy Compilers" won't hurt.)
 * Close Eclipse
 ==Setup workspace==
-===Install freeplane_bin===
-# Download the current Freeplane binary distribution (e.g. freeplane-1.2.13.zip) and unpack it into the selected workspace
-# Rename the latter directory into '''''freeplane_bin''''' and make sure this directory is in the workspace.
-On the command line (Linux/Unix/Mac):
-    cd <workspace> # your selected workspace, like ~/freeplanescripts
-    unzip freeplane_bin-1.2.13.zip
-    mv freeplane-1.2.13 freeplane_bin
 ===Install freeplane_src===
-Download matching Freeplane source distribution (e.g. freeplane_src-1.2.13.tar.gz) and unpack it into the selected workspace. Unpacking this archive may require an additional program like 7zip, jzip or winzip on Windows (check by trying to open the file in the Explorer). Unpacking may need two steps:
+This is for installing freeplane_src for the first time. For updating it, read [[#How to upgrade freeplane_src version|How to upgrade freeplane_src version]].
+Download the current Freeplane source distribution (e.g. freeplane_src-1.2.13.tar.gz) and unpack it into the selected workspace. Unpacking this archive may require an additional program like 7zip, jzip or winzip on Windows (check by trying to open the file in the Explorer). Unpacking may need two steps:
 # In a program like 7zip open the archive freeplane_src-1.2.13.tar.gz. Most unpackers will allow directly extract into a directory, but jzip creates an intermediate freeplane_src-1.2.13.tar file
 # Rename freeplane-1.2.13 into freeplane_src and make sure this directory is in the workspace.
-On the command line (Linux/Unix/Mac):
+On the command line (Linux/Unix/Mac, Windows 10 now also supports <code>tar</code> but use <code>rename</code> instead of <code>mv</code>):
      cd <workspace> # your selected workspace, like ~/freeplanescripts
      tar -xzvf freeplane_src-1.2.13.tar.gz
      mv freeplane-1.2.13 freeplane_src
+For Freeplane >= 1.5 you need to create a gradle build:
+* You need at least gradle 2.x (install a gradle binary distribution if you need to)
+* Create a full gradle build by issuing the following command in the freeplane_src directory:
+  $ gradle clean build cleanEclipse eclipse
+Alternatively you can use [[#How to set up your environment with the Eclipse Plug-ins for Gradle|the Eclipse Plug-ins for Gradle]].
+For Freeplane < 1.5 you do not have to perform a build.
 ===Install groovy support===
 Freeplane's regular script directory <freeplaneuserdir>/scripts will be the script project directory where script development happens. To add special support for Freeplane scripting you have to copy the file ''freeplane_bin/scripts/freeplane.dsld'' to the script directory.
@@ Line 35: / Line 38: @@
 ==Create projects==
-=== Create a Java Project for the Freeplane binaries ===
+=== Import the Freeplane project(s) ===
+The Freeplane sources in ''freeplane_src'' consist of multiple projects, which are prepared for Eclipse. We can simply import this projects into our Eclipse workspace:
-[[File:Eclipse-create-project-freeplane_bin-0.png|700px|border]]
+. Select File->Import...
-. Set the project name to the name of the folder containing the Freeplane binaries
+[[File:Eclipse-setup-import-project-select1.png|300px|border]]
-[[File:Eclipse-create-project-freeplane_bin-1.png|500px|border]]
-. Allow scripts access to the Freeplane libraries
+. Set the root directory to ''<workspace>/freeplane_src'' and select all projects except ''freeplane-ant'' and (unless this happens on a Mac) ''freeplane-mac''. Then click "Finish".
-[[File:Eclipse-create-project-freeplane_bin-2.png|500px|border]]
+[[File:Eclipse-setup-import-project-select2.png|500px|border]]
-=== Create a Groovy Project for the scripts ===
+=== Create a Groovy project for the scripts ===
+(You may have to click on "Other..." to see "Groovy project" option.)
 [[File:Eclipse-create-project-scripts-0.png|700px|border]]
-. Set the project name to the name of the folder containing the scripts
-[[File:Eclipse-create-project-scripts-1.png|500px|border]]
-. Connect the scripts with the Freeplane libraries.
+. Set the project name to "scripts", uncheck "Use default location" and enter the full path to the freeplane scripts folder (<freeplaneuserdir>/scripts):
- [[File:Eclipse-create-project-scripts-2.png|700px|border]]
+[[File:Eclipse-create-project-scripts-1.png|450px|border]]
-. Select a different build output folder. Otherwise a lot of .class files would pollute the scripts directory. This is not required but helpful.
-[[File:Eclipse-create-project-scripts-3.png|900px|border]]
+. Connect the scripts with Freeplane.
-=== Connect the scripts with the Freeplane source files ===
+ [[File:Eclipse-create-project-scripts-2.png|450px|border]]
-. Type Shift+Ctrl+T ("Open Type") and enter "freeeplanescript" to open the class FreeplaneScriptBaseClass.
-[[File:Eclipse-connect-to-freeplane-sources-0.png|450px]]
+. Select a different build output folder. Otherwise a lot of .class files would pollute the scripts directory. This step is not required but helpful.
-. The source for the class can not be found. Click on "Attach source", then "External folder" and browse to the freeplane_src directory in the workspace
+[[File:Eclipse-create-project-scripts-3.png|900px|border]]
-[[File:Eclipse-connect-to-freeplane-sources-1.png|700px]]
+Done. You can proceed now with page [[Edit scripts in Eclipse]].
-and click OK. The source of the class is shown now.
+== How to upgrade freeplane_src version ==
-==Using Eclipse==
+In case you want to upgrade your environment to a newer freeplane_src you can remove the old version first with the following steps:
-=== Edit a script ===
-[[File:Eclipse-edit-script.png|900px|border]]
-===Magic keys===
+# Right-click on your project(s) and choose Build Path > Configure Build Path... and then the Projects tab
-* ALT+Space
+# On this tab: select all Freeplane (source) projects, click Remove and then OK
-** Initiates content assist, completes typed texts.
+# Close your project(s)
-** Import declarations for completed types are automatically added.
+# Select all Freeplane (source) projects, press delete and then OK
-** Example: type "str" (without the quotes) and hit ALT space.
+# Go to your freeplane_src directory and delete all files
-* F3
+# Now you can [[#Install freeplane_src|install freeplane_src]] for the new Freeplane version and [[#Import the Freeplane project(s)|import the Freeplane projects]] or use the steps for [[#How to set up your environment with the Eclipse Plug-ins for Gradle|the Eclipse Plug-ins for Gradle]]
-** Navigates to the definition of the variable/class under the cursor.
+# Open your project(s)
-** This also works for Java and Freeplane classes - allowes to lookup details of the class.
+# Right-click on your project(s) and choose Build Path > Configure Build Path... and then the Projects tab
-* ALT+Cursor_Left
+# On this tab: click Add, add the Freeplane projects and click OK twice
-** Navigates to the last remembered location.
-* Shift+Ctrl+T
-** Open a type (e.g. a class or interface).
-** Try entering "proxy" and select the Proxy from org.freeplane.plugin.script.proxy
-** Proxy is the API definition.
-* Shift+Ctrl+R
-** Use this to open a script
+Removing (step 1 and 2) and adding (step 8 and 9) the Freeplane projects to your build path are a foolproof way to ensure that your build path stays correct. You can skip them, but be sure to check if your build path is still correct because names and number of Freeplane project tend to change from time to time.
-=== Making available groovy classes to your mind map===
+== How to set up your environment with the Eclipse Plug-ins for Gradle ==
-If in Eclipse you define and run Hello.groovy, Eclipse compiles and saves it as Hello.class in the build output folder you specified above. If you supplied a package name in the script e.g. <tt>package hellopackage</tt>, this name is used as a subdirectory, hellopackage/Hello.class. If you used the default (which it advised for scripts), it is just Hello.class.
-* Open Freeplane and open Tools > Preferences > Plugins.
+This is an alternative for the steps in [[#Install freeplane_src|install freeplane_src]] and [[#Import the Freeplane project(s)|import the Freeplane projects]]
-On the last row add the path to directory where Eclipse saves the compiled classes:
-* If you followed the procedure above the build output folder is scripts/bin in the Freeplane user directory. In this case enter <tt>scripts/bin</tt>.
-* If you have choosen some other directory (e.g. in the Eclipse workspace) you have to specify the full path.
-In Windows 7 this has the following complication. Suppose them full path to the example class Hello.class is:
+'''Precondition'''
-''C:/Gebruikers/Beheerder/workspaceFP/scripts/bin/hellopackage/Hello.class'' or ''C:/Gebruikers/Beheerder/workspaceFP/scripts/bin/Hello.class'' (if you did not specify a package name) then in either case the path must be: C:\Users\Beheerder\workspaceFP\scripts\bin
-Note that (1) "Beheerder", which is shown in the regular directory path and is - in this case the dutch - translation of users, MUST be replaced by the English USERS. Note further (2) that all slashes MUST BE backslashes.
-* To take effect, restart Freeplane. (In case of problems, check the log file if Freeplane did could install the path).
+You have "Buildship: Eclipse Plug-ins for Gradle" installed in Eclipse. It is probably already included with your Eclipse if you installed one of the newer versions.
-* If you did specify a package name, then add an import statement for the class like ''import hellopackage.Hello''. This is automatically added by Eclipse if you use the code completion (do that!) for the class name: After entering ''def hello = new hell'' hit Ctrl+Space:
+'''Steps'''
-[[File:Eclipse-code-completion1.png|500px|border]]
-Choosing the first suggestion results in
+# Download freeplane_src-x.x.x.tar.gz
+# Extract to your Eclipse workspace: <code>tar -xvzf <downloads>/freeplane_src-x.x.x.tar.gz -C <workspace></code>
+# Rename directory freeplane-x.x.x to freeplane_root: <code>rename freeplane-x.x.x freeplane_root</code> (use <code>mv</code> for Linux/Unix/Mac)
+# In Eclipse click/select Run > Run configurations
+# Right click Gradle Task and choose New Configuration
+# Rename 'New_configuration' to 'Build Freeplane'
+# In Gradle Tasks add: clean, build and dist (so 3 tasks on 3 separate lines)
+# Click/select File System... > <workspace>/freeplane_root > OK
+#; [[File:Build Freeplane Run Configuration.png]]
+# Click Run and wait till Gradle build has finished
+# Click/select File > Import > Existing Gradle Project > Next > Next
+# Specify the path to the <workspace>/freeplane_root directory in 'Project root directory' and click Finish. All projects are now imported as Gradle projects
+# Delete freeplane_ant (and freeplane_mac if you ar not on Mac)
-[[File:Eclipse-code-completion2.png|500px|border]]
+Steps 4 to 9 are necessary to prevent an error in <code>freeplane_plugin_jsyntaxpane</code>: it needs to be built before it can be imported. It also prepares for running Freeplane from within Eclipse for [[Debugging scripts]]
 [[Category:Script]]

Difference between revisions of "Scripting environment setup"

Latest revision as of 07:52, 6 September 2021

Contents

Installations

Setup workspace

Install freeplane_src

Install groovy support

Create projects

Import the Freeplane project(s)

Create a Groovy project for the scripts

How to upgrade freeplane_src version

How to set up your environment with the Eclipse Plug-ins for Gradle

Navigation menu

Views

Personal tools

Navigation

Quick Links

Search

Tools