Difference between revisions of "Developer Documentation"

From ApCoCoAWiki
 
(74 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=ApCoCoA 2 Developer Documentation=
+
The ApCoCoA 2.0 project is divided into two sub projects: The CoCoA Plugin and the CoCoA IDE based on IntelliJ.
  
The ApCoCoA 2.0 project is divided in two sub projects: The CoCoA Plugin and the CoCoA IDE based on Intellij.
+
=The CoCoA IDE=
 
+
The IDE is based on [https://github.com/JetBrains/intellij-community IntelliJ Community Edition]. The source code of the
=The CoCoA Ide=
+
IntelliJ Community Edition is available on Github. We cloned the original repository and modified some files in the python branch to make our own customized IDE (ApCoCoA). The repository on which we are working now is available at: https://fimgit.fim.uni-passau.de/walsh/apcocoa-ide.
The IDE is based on Intellij community edition.
 
https://github.com/JetBrains/intellij-community. The source code of the
 
Intellij Community edition is available on github. We simply cloned the
 
original repository and modified some files in the python branch to
 
make our own customized IDE(ApCoCoA). However the repository on
 
which we are working now is available on bitbucket:
 
https://bitbucket.org/klausnguets/cocoa_ide/src/master/.
 
 
We modified the following files in the IDE:
 
We modified the following files in the IDE:
* In the python/resources folder you we replaced the IDE logos with our own logo.
+
* In the folder ''python/resources'' we replaced the IDE logos with our own logo.
* In python/python-community-ide-resources/resources/tips you can find the files to modify the product name, the help page etc.
+
* In ''python/python-community-ide-resources/resources/tips'' you can find the files to modify the product name, the help page etc.
* In the same python/python-community-ide-resources/resources folder you can find the file (/idea/PyCharmCoreApplicationInfo.xml)
+
* In the same folder ''python/python-community-ide-resources/resources'' you can find the file ''/idea/PyCharmCoreApplicationInfo.xml'' to edit the IDE information.
to edit the IDE informations. There is more one can customize. Please refer to the github page https://github.com/JetBrains/intellij-community or to the intelliJ Platform SDK DevGuide https://jetbrains.org/intellij/sdk/docs/intro/about.html.
+
* In the built IDE the logos can be found (and changed) in ''lib/pycharm.jar'' other information like the version number is contained in ''lib/pycharm.jar/idea/PyCharmCoreApplicationInfo.xml''
 +
There is more one can customize. Please refer to the [https://github.com/JetBrains/intellij-community Github page] or to the [https://jetbrains.org/intellij/sdk/docs/intro/about.html IntelliJ Platform SDK DevGuide].
  
 
=Building the IDE=
 
=Building the IDE=
 
After the the IDE is customized as wanted, the last step is to build the
 
After the the IDE is customized as wanted, the last step is to build the
sources in order to obtain the IDE for windows, linux and mac as follows:
+
sources in order to obtain the IDE for Windows, Linux and Mac as follows:
* First install ant https://ant.apache.org/.
+
* Install [https://ant.apache.org/ Ant], the Java Development Kit and JavaFX.
On ubuntu, a sudo apt-get install ant would be enough.
+
 
* Increase the Java Heap size for ant: > export ANT_OPTS="-Xmx5g -
+
* Increase the Java Heap size for ant: <code>export _JAVA_OPTIONS=-Xmx5000m</code> to set a maximum heap size of for example 5G. To make those changes permanent, you have to add this command in your ''/etc/profile''. <br/>You can use the command <code>java -XshowSettings:vm</code> to check whether the heap size has changed.
XX:-UseGCOverheadLimit" or use export _JAVA_OPTIONS=-
+
 
Xmx5000m to set a maximum heap size of 5G for example. To make
+
* Change to the folder ''python'' in the source and run the command <code>ant -f build.xml</code>. You might get a <code>BUILD FAILED</code> error message. You can ignore this message but need to make sure that in the directory ''out/pycharm-ce'' the three folders ''dist.mac'', ''dist.unix'' and ''dist.win'' were created.
those changes permanent, you have to add those commands in the
+
 
/etc/profile
+
* To obtain the IDE for a given platform, for example Unix, copy the contents of ''dist.unix/run'' and ''dist.unix/lib'' into the folders ''dist.all/run'' and ''dist.all/lib'' respectively.
* cd to the folder python in the source and run the command ant -f
+
 
build.xml
+
* Make the files ''pycharm.sh'', ''fsnotifier'' and ''fsnotifier64'' executable: <code>chmod +x ./fsnotifier ./fsnotifier64 ./pycharm.sh</code>.
The build generates in the directory python/out/pycharm-ce three folders:
+
 
dist.mac, dist.unix, dist.win which contain the builded IDEs for the different
+
* Now you should be able to start the IDE using <code>./pycharm.sh</code>.
platforms.
 
  
 
=The CoCoA Plugin=
 
=The CoCoA Plugin=
The CoCoA plugin is the part of the project which adresses everything that
+
The CoCoA plugin is the part of the project which addresses everything that is specific to the CoCoA language such as the syntax highlighting, the
is specific to the CoCoA language such as the syntax highlighting, the
 
 
interpreter, the interactive window, the CoCoA files recognition...
 
interpreter, the interactive window, the CoCoA files recognition...
The plugin is developped as a normal intellij Platform plugin, meaning it can
+
The plugin is developed as a normal IntelliJ Platform plugin, meaning it can be used in other IntelliJ IDEs to make them recognize and interpret a CoCoA file. IntelliJ platforms provides interesting tutorials on plugin creation:
be used in other intellij IDEs to make them recognize and interpret a CoCoA
+
[https://jetbrains.org/intellij/sdk/docs/basics/getting_started.html Getting Started],
file. Intellij platforms provides interesting tutorials on plugin creation:
+
[https://jetbrains.org/intellij/sdk/docs/basics/getting_started/creating_plugin_project.html Creating a Plugin Project].
https://jetbrains.org/intellij/sdk/docs/basics/getting_started.html,
+
Our plugin project is located in a repository at https://fimgit.fim.uni-passau.de/walsh/apcocoa-plugin
https://jetbrains.org/intellij/sdk/docs/basics/getting_started/
 
creating_plugin_project.html
 
Our plugin project is located in bitbucket at
 
https://bitbucket.org/klausnguets/apcocoa_plugin/src/master/
 
  
=Plugin implementation=
+
=Plugin Implementation=
The plugin implementation has 3 packages: com.cocoaplugin.ide,
+
The plugin implementation has 3 packages: com.cocoaplugin.ide, com.cocoaplugin.psi, com.cocoaplugin.run.  
com.cocoaplugin.psi, com.cocoaplugin.run.
+
===com.cocoaplugin.psi===
com.cocoaplugin.psi
+
In this package you will find the logic about the CoCoA Parser for syntax highlighting, and all other logic related to the CoCoA language itself. For more information on this topic please refer to the [https://jetbrains.org/intellij/sdk/docs/intro/about.html IntelliJ Platform SDK DevGuide].
In this package you will find the logic about the Cocoa Parser for syntax
+
 
highlighting, and all other logic related to the cocoa language itself. For
+
===com.cocoaplugin.run===
more information about this topic please refer to the IntelliJ Platform SDK
+
This package contains the logic to create a run configuration for CoCoA. It is not very important for the plugin to work but with a run configuration someone can send a CoCoA file to the interpreter without using the interactive windows or the CoCoA window.
DevGuide here: https://jetbrains.org/intellij/sdk/docs/intro/about.html .
+
IMPORTANT: if you are building the plugin for windows or another OS please make sure the INTERPRETER_PATH in the class CocoaRunConfigurationProducer of this package is correct for that OS.
2com.cocoaplugin.run
+
 
This package contains the logic to create a run configuration for cocoa. It is
+
===com.cocoaplugin.ide===
not very important for the plugin to work but with a run configuration
 
someone can send a cocoa file to the interpreter without using the
 
interactive windows or the cocoa window.
 
IMPORTANT: if you are building the plugin for windows or another OS
 
please make sure the INTERPRETER_PATH in the class
 
CocoaRunConfigurationProducer of this package is correct for that OS.
 
com.cocoaplugin.ide
 
 
This package is the most important package of the project as here you have
 
This package is the most important package of the project as here you have
 
the logic for the interactive Window, the events “send to Cocoa”, “refresh
 
the logic for the interactive Window, the events “send to Cocoa”, “refresh
Line 70: Line 51:
 
Let’s choose some important classes in this package and give a brief
 
Let’s choose some important classes in this package and give a brief
 
description of them:
 
description of them:
* CocoaProcessManager
+
* CocoaProcessManager <br/> In this class we manage the CoCoA interpreter process running in the background. It automatically detects the operating system and determines the path to the CoCoA-Interpreter. This is somewhat of a workaround. To function correctly it is important that the plugin jar is named ''apcocoa-plugin.jar'' since we determine all paths relative to this file.
This class is the class where we manage the cocoa interpreter process
+
* InterpreterThread <br/> This class represents the thread which reads the results produced by CoCoA. It listens to the standard output of the CoCoA interpreter process and whenever there is a result available, it prints it back to the user in the CoCoA output window.
running in the background. Again make sure the right interpreter path
+
* SendToCocoa <br/> This class is an [https://jetbrains.org/intellij/sdk/docs/tutorials/action_system/working_with_custom_actions.html?search=action IntelliJ Action] When the user starts the action “send to cocoa” we get the text selection and write it to the input of the cocoa interpreter process, and later the result will be read by the InterpreterThread as explained above.
for the targeted OS is given(line 32).
+
* CocoaInteractiveWindow <br/> This is the cocoa interactive window. It interacsts with the two other classes TerminalFilter and TerminalNavigationFilter.
* InterpreterThread
+
* CocoaToolWindow <br/> This class is the window for the CoCoA Outputs. For more about IntelliJ ToolWindows, please refer again to the IntelliJ Platform SDK DevGuide
This class represents the thread which reads the results produced by
+
 
cocoa. It listens to the standard output of the cocoa interpreter
+
=Building the Plugin=
process and whenever there is a result available, it prints it back to the
+
* Clone the plugin project from the repository and open it in IntelliJ
user in the cocoa output window.
+
* Choose the IntelliJ Platform SDK as SDK for the project. To do this follow the instructions described here: [https://jetbrains.org/intellij/sdk/docs/basics/getting_started/setting_up_environment.html Setting Up a Development Environment]
* SendToCocoa
+
* Make sure the ''resources'' folder is marked as resources root
This class is an Intellij action ( https://jetbrains.org/intellij/sdk/docs/tutorials/
+
* Then you can build the plugin using the menu option “Build > Prepare module apcocoa_plugin for Deployment”.
action_system/working_with_custom_actions.html?search=action )
+
* A jar file ''apcocoa-plugin.jar'' will be generated in the project folder
When the user starts the action “send to cocoa” we get the text
 
selection and write it to the input of the cocoa interpreter process,
 
3and later the result will be read by the InterpreterThread as explained
 
above.
 
* CocoaInteractiveWindow
 
This is the cocoa interactive window. It interacsts with the two other
 
classes TerminalFilter and TerminalNavigationFilter.
 
* CocoaToolWindow
 
This class is the window for the cocoa Outputs. For more about IntellIj
 
ToolWindows, please refer again to the IntellIj IntelliJ Platform SDK
 
DevGuide
 
  
 
=Deployment=
 
=Deployment=
ApCoCoA can be simply distributed using the files generated during the
+
You can create the final ApCoCoA by following the steps below. We assume that you built the IDE and that it is now in the folder ''dist''.
building process. But the plugin also have to be integrated in the final
+
 
distribution file. For that, you have to build the plugin.
+
* Build the plugin as described above.
In Intellij open the plugin project and go to “Build > Prepare module
+
* Move the jar file ''apcocoa-plugin.jar'' and the folder ''cocoa'' from the plugin project to the folder ''dist/plugins/apcocoa/lib/'' <br/> The ''cocoa'' folder contains the CoCoA-Interpreter and the help files.
apcocoa_plugin for Deployment”. A jar file(apcocoa_plugin.jar) will be
+
* Rename the file ''dist/bin/pycharm.sh'' to ''apcocoa.sh''. After making the file executable, you should be able to run ApCoCoA.
generated in the project directory. Finally, move that plugin file to the
+
* Currently the file template and run configuration for CoCoA have to be added manually. To make these changes permanent you need to change the file ''bin/idea.properties'' (just copy it from a previous ApCoCoA version)
dist.[os]/plugins/apcocoa/lib/ you want to distribute.
+
 
When ApCoCoA starts, we always check whether the user has a CoCoA
+
[[Category:ApCoCoA Installation]]
interpreter in his or her system already. Otherwise we copy the cocoa
 
interpreter to the user’s home directory. How this is done can be found in
 
the file bin/start.sh or bin/start.bat(windows) of the current ApCoCoA.
 

Latest revision as of 08:21, 18 October 2022

The ApCoCoA 2.0 project is divided into two sub projects: The CoCoA Plugin and the CoCoA IDE based on IntelliJ.

The CoCoA IDE

The IDE is based on IntelliJ Community Edition. The source code of the IntelliJ Community Edition is available on Github. We cloned the original repository and modified some files in the python branch to make our own customized IDE (ApCoCoA). The repository on which we are working now is available at: https://fimgit.fim.uni-passau.de/walsh/apcocoa-ide. We modified the following files in the IDE:

  • In the folder python/resources we replaced the IDE logos with our own logo.
  • In python/python-community-ide-resources/resources/tips you can find the files to modify the product name, the help page etc.
  • In the same folder python/python-community-ide-resources/resources you can find the file /idea/PyCharmCoreApplicationInfo.xml to edit the IDE information.
  • In the built IDE the logos can be found (and changed) in lib/pycharm.jar other information like the version number is contained in lib/pycharm.jar/idea/PyCharmCoreApplicationInfo.xml

There is more one can customize. Please refer to the Github page or to the IntelliJ Platform SDK DevGuide.

Building the IDE

After the the IDE is customized as wanted, the last step is to build the sources in order to obtain the IDE for Windows, Linux and Mac as follows:

  • Install Ant, the Java Development Kit and JavaFX.
  • Increase the Java Heap size for ant: export _JAVA_OPTIONS=-Xmx5000m to set a maximum heap size of for example 5G. To make those changes permanent, you have to add this command in your /etc/profile.
    You can use the command java -XshowSettings:vm to check whether the heap size has changed.
  • Change to the folder python in the source and run the command ant -f build.xml. You might get a BUILD FAILED error message. You can ignore this message but need to make sure that in the directory out/pycharm-ce the three folders dist.mac, dist.unix and dist.win were created.
  • To obtain the IDE for a given platform, for example Unix, copy the contents of dist.unix/run and dist.unix/lib into the folders dist.all/run and dist.all/lib respectively.
  • Make the files pycharm.sh, fsnotifier and fsnotifier64 executable: chmod +x ./fsnotifier ./fsnotifier64 ./pycharm.sh.
  • Now you should be able to start the IDE using ./pycharm.sh.

The CoCoA Plugin

The CoCoA plugin is the part of the project which addresses everything that is specific to the CoCoA language such as the syntax highlighting, the interpreter, the interactive window, the CoCoA files recognition... The plugin is developed as a normal IntelliJ Platform plugin, meaning it can be used in other IntelliJ IDEs to make them recognize and interpret a CoCoA file. IntelliJ platforms provides interesting tutorials on plugin creation: Getting Started, Creating a Plugin Project. Our plugin project is located in a repository at https://fimgit.fim.uni-passau.de/walsh/apcocoa-plugin

Plugin Implementation

The plugin implementation has 3 packages: com.cocoaplugin.ide, com.cocoaplugin.psi, com.cocoaplugin.run.

com.cocoaplugin.psi

In this package you will find the logic about the CoCoA Parser for syntax highlighting, and all other logic related to the CoCoA language itself. For more information on this topic please refer to the IntelliJ Platform SDK DevGuide.

com.cocoaplugin.run

This package contains the logic to create a run configuration for CoCoA. It is not very important for the plugin to work but with a run configuration someone can send a CoCoA file to the interpreter without using the interactive windows or the CoCoA window. IMPORTANT: if you are building the plugin for windows or another OS please make sure the INTERPRETER_PATH in the class CocoaRunConfigurationProducer of this package is correct for that OS.

com.cocoaplugin.ide

This package is the most important package of the project as here you have the logic for the interactive Window, the events “send to Cocoa”, “refresh cocoa” , as well as the multithreading used to separate the interpreter threads from the IDE thread in order to avoid blocking everything when cocoa is calculating. Let’s choose some important classes in this package and give a brief description of them:

  • CocoaProcessManager
    In this class we manage the CoCoA interpreter process running in the background. It automatically detects the operating system and determines the path to the CoCoA-Interpreter. This is somewhat of a workaround. To function correctly it is important that the plugin jar is named apcocoa-plugin.jar since we determine all paths relative to this file.
  • InterpreterThread
    This class represents the thread which reads the results produced by CoCoA. It listens to the standard output of the CoCoA interpreter process and whenever there is a result available, it prints it back to the user in the CoCoA output window.
  • SendToCocoa
    This class is an IntelliJ Action When the user starts the action “send to cocoa” we get the text selection and write it to the input of the cocoa interpreter process, and later the result will be read by the InterpreterThread as explained above.
  • CocoaInteractiveWindow
    This is the cocoa interactive window. It interacsts with the two other classes TerminalFilter and TerminalNavigationFilter.
  • CocoaToolWindow
    This class is the window for the CoCoA Outputs. For more about IntelliJ ToolWindows, please refer again to the IntelliJ Platform SDK DevGuide

Building the Plugin

  • Clone the plugin project from the repository and open it in IntelliJ
  • Choose the IntelliJ Platform SDK as SDK for the project. To do this follow the instructions described here: Setting Up a Development Environment
  • Make sure the resources folder is marked as resources root
  • Then you can build the plugin using the menu option “Build > Prepare module apcocoa_plugin for Deployment”.
  • A jar file apcocoa-plugin.jar will be generated in the project folder

Deployment

You can create the final ApCoCoA by following the steps below. We assume that you built the IDE and that it is now in the folder dist.

  • Build the plugin as described above.
  • Move the jar file apcocoa-plugin.jar and the folder cocoa from the plugin project to the folder dist/plugins/apcocoa/lib/
    The cocoa folder contains the CoCoA-Interpreter and the help files.
  • Rename the file dist/bin/pycharm.sh to apcocoa.sh. After making the file executable, you should be able to run ApCoCoA.
  • Currently the file template and run configuration for CoCoA have to be added manually. To make these changes permanent you need to change the file bin/idea.properties (just copy it from a previous ApCoCoA version)