Developer Documentation
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 IntelliJ Community Edition (https://github.com/JetBrains/intellij-community). 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). 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:
- In the folder
python/resourceswe replaced the IDE logos with our own logo. - In
python/python-community-ide-resources/resources/tipsyou can find the files to modify the product name, the help page etc. - In the same folder
python/python-community-ide-resources/resourcesyou can find the file/idea/PyCharmCoreApplicationInfo.xml>/code> 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.
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:
- First install ant https://ant.apache.org/.
On ubuntu, a sudo apt-get install ant would be enough.
- Increase the Java Heap size for ant: > export ANT_OPTS="-Xmx5g -
XX:-UseGCOverheadLimit" or use export _JAVA_OPTIONS=-
Xmx5000m to set a maximum heap size of 5G for example. To make
those changes permanent, you have to add those commands in the
/etc/profile
- cd to the folder python in the source and run the command ant -f
build.xml
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
platforms.
The CoCoA Plugin
The CoCoA plugin is the part of the project which adresses 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 developped 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:
https://jetbrains.org/intellij/sdk/docs/basics/getting_started.html,
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
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 about this topic please refer to the IntelliJ Platform SDK
DevGuide here: https://jetbrains.org/intellij/sdk/docs/intro/about.html .
2com.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
This class is the class where we manage the cocoa interpreter process
running in the background. Again make sure the right interpreter path
for the targeted OS is given(line 32).
- 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 ( https://jetbrains.org/intellij/sdk/docs/tutorials/
action_system/working_with_custom_actions.html?search=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,
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
ApCoCoA can be simply distributed using the files generated during the
building process. But the plugin also have to be integrated in the final
distribution file. For that, you have to build the plugin.
In Intellij open the plugin project and go to “Build > Prepare module
apcocoa_plugin for Deployment”. A jar file(apcocoa_plugin.jar) will be
generated in the project directory. Finally, move that plugin file to the
dist.[os]/plugins/apcocoa/lib/ you want to distribute.
When ApCoCoA starts, we always check whether the user has a CoCoA
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.
