OpenCobolIDE Documentation

Transcription

1 OpenCobolIDE Documentation Release beta Colin Duquesnoy July 03, 2014

2

3 Contents 1 Parts of the documentation: What s New? Download & Install Getting started FAQ Contributing License Meta information: 19 3 Indices and tables: 21 4 Disclaimer 23 i

4 ii

5 OpenCobolIDE is a simple and lightweight cobol IDE based on the OpenCobol/Gnu Cobol compiler and the pyqode source code editor widget. Contents 1

6 2 Contents

7 CHAPTER 1 Parts of the documentation: 1.1 What s New? This page lists the most prominent milestones achieved by the OpenCobolIDE developers. For more specific details about what is planned and what has been accomplished, please visit the issues page on github Next Version We don t have any plans for the next release. Please report bugs and share your thoughts to make OpenCobolIDE better! Changelog New features: add Mac OSX support move to PyQt5 (to support retina screens) add support for pyqode 2.0: the new api is a lot more stable API and is now fully tested. The editor style and performances have been improved but the folding panel has been temporarely removed (for performance reason) new user interface: the menu and toolbar has gone, instead there is now a compile and run button inside the editor and a drop down button in the status bar for the most important actions. The homepage and the preferences dialog also got redesigned. compiler process management has been improved: We are now using QProcess instead of subprocess, this allow some neat improvements such as auto compile before run. better log message + log window: include information from the log window when you report bugs! Please, read the Getting started section of this manual to get started with the new user interface! 3

8 2.3.1 drop python 2 support (the main script must now be run by a python3 interpreter) fix bug with encoding error, see bug #31 on github New features: Fixed bugs: add ability to run the compiled programe in an external terminal. This is useful if you are using the SCREEN SECTION as the embedded terminal does not support redirection. fix bug with detection of submodules call if they are enclosed with single quotes instead of double quotes New features: pic fields offsets calculator case converter, you can convert selected text to lower or TO UPPER using the editor context menu. full dark style using qdarkstyle new test suite for compiler and parser modules improved go to line dialog add support for _*.pco_ and _*.cpy_ files Fixed bugs: fix compilation for file if path contains spaces (Linux and Windows) fix parser crash that prevents from compiling improve cobol parser to support malformed syntax fix ambiguous shortcut overload: F2 fix outline not informative for cobol files that have data in column New features: Go to definition for variables and procedures (ctrl + click on symbol) New debian package on ppa:open-cobol-ide/stable and ppa:open-cobol-ide/unstable Fixed Bugs: code completion should not occur in comments and strings fix column number for navigation panel 4 Chapter 1. Parts of the documentation:

9 2.0.1 Fixed Bugs: removed un-needed import of pexpect which caused some issue on clean system which does not have pexepect This new release is a major update which makes the transition from PCEF to pyqode. Most of the application has been rewritten from scratch. Here are the major changes: port to pyqode 1.0 new compiler errors panel interactive output console for program output uses pyqode.qt in place of PySide support for both python 2 and python 3 on the fly syntax check, OpenCobolIDE compile your code in the background to quickly warn you about wrong syntax. better integration with most linux desktop environments (use icons and colors from theme, desktop entry). Tested with KDE, Gnome, Unity and Cinnamon. allow user to type in lower case ( Update code so support pcef Fixed Bugs: slow in large files: New features: Fixed Bugs: shortcuts for dock windows (F9: log panel, F10: navigation panel) show fullscreen shortcut change from F12 to F11 the application will restore its geometry and state (maximised, dock window positions) dock panel shown when switching tab: now the panel is only show when coming from the homepage or when compiling crash when editing/compiling files who have unicode characters in their path focus lost when opening recent files from the menu or the homepage on ubuntu > What s New? 5

10 Enhancements and fixed bugs in PCEF 0.2.0: improve performances in general support for custom word separator, allow OpenCobolIDE to remove the - character from word separators which brings a better code completion for cobol dirty flag is correctly updated scrollbars are now correctly update when folding/unfolding code blocks This release improves usability with a focus on the run and compile actions: detect source dependencies and compile them (if a program P requires a subprogram A who requires a subprogram B than the IDE will compile A, B and P) Automatically compile file when the run action is triggered Run the last program if the current tab is a subprogram Avoid compiling a file that is already compiled and up to date Fix bug: Added: Home page with list of recent files A settings page to change a few options (mainly related to the editor style) A navigation panel to quickly browse large files (tree with div, sections, variables and paragraphs) A shortcut to comment/uncomment selected or active lines (ctrl+/) On GNU/Linux, at first start the program will ask the user if he wants to create a desktop files Bug fixes: windows path not normalized fix bug with mingw when path contains spaces on windows fix bug where no extension was proposed when creating a new file better encoding detection using chardet cobol specific code completion model status bar infos (filename, encoding, cursor position) windows port (a windows installer is available in the download section) 6 Chapter 1. Parts of the documentation:

11 1.0.1 fix packaging issues Initial development 1.2 Download & Install Here you ll find all the necessary explanations for installing OpenCobolIDE Requirements: OpenCobolIDE depends on the following packages: Python 3 PyQt5 OpenCobol pyqode.core pygments >= 1.6 chardet GNU/Linux Install pyqt5, open-cobol and pip using your package manager, then run the following commands: sudo pip3 install OpenCobolIDE If you are on Archlinux, you can install OpenCobolIDE and all its dependencies from the AUR: Windows There is a windows installer available here: Mac OSX There is a dmg image available here: The only thing you have to do is: to install OpenCobol compiler, e.g. using homebrew: brew install open-cobol run the OpenCobolIDE app 1.2. Download & Install 7

12 Note: If you installed the compiler in a non-standard path and it is not recognized, you can specify and the path to the compiler in the preferences dialog under the Build & Run section. Just make sure to only specify the directory where the compiler can be found, not the full path. 1.3 Getting started Note: All the screenshots were taken on Gnome 3 desktop. You will have different looks and feels on other OS/DE. This is the first window you will see when running OpenCobolIDE. This is your home page. From there you can create new files or open existing one. OpenCobolIDE is simple and lightweight IDE. It works on a single file basis (i.e. it has no concept of project): You create/open a file, compile it then run it Create a new file click on New the following dialog should appear: 8 Chapter 1. Parts of the documentation:

13 fill up the following information: Type: Specify the type of file to create. You can choose from * program: A program is an executable. When compiled, it produces an.exe on Windows and an executable binary file on GNU/Linux and Mac OSX. * module: A module or subprogram is a library, a list of procedures that can be shared among other modules/programs. When compiled, it produces a dynamically linked library (.dll) on Windows and a shared object (.so) on GNU/Linux and Mac OSX. * empty: create an empty file. The type can be changed later. It used now to setup the default code skeleton, to simplify your life ;) Name: file name without extension (you can choose the extension in the drop down list) Directory: directory where the file will be created. Warning: Modules source code must be in the same directory as the parent program source code to work properly Open a file Simply click on Open or choose a file in the recent files list. Note: The recent files list have a context menu that let you remove a file or clear the entire list The main window Here is the main window of OpenCobolIDE: 1.3. Getting started 9

14 It is made up of 4 important parts: 1. the text editor tabs: This is where you type your code. 2. the navigation panel (movable and closable): This panel show you the structure of your code and let you navigate quickly inside your document. 3. The Log panel (movable and closable): 4. the status bar: This panel show various log and output. It is made up of the following tabs: Compilation output: textual output of the cobol compiler Issues: the list of issues Output: the program output (when you run it). The output console is interactive and accepts stdin. Application log: the application log, for debugging purpose. This window is not visible when you start the IDE. You can show it by checking: menu -> View -> Appplication log -> Show window 10 Chapter 1. Parts of the documentation:

15 Since version 2.4, the status bar has become an important part of the application as it now contains the preferences button and the general menu as a drop down menu button: You can click on the button to show the preferences dialog or click on the arrow to reveal the general menu (Open, New, View, Help,...) Compile a file To compile a file, press F8 or press the compile button (inside the editor). This will compile the current file but also the referenced modules. The compiler output will automatically be shown: 1.3. Getting started 11

16 You can double click on an entry in the issues table to quickly go to the problematic line in the code editor (if the file hasn t been open, OpenCobolIDE will gently open it for you). To change the program type you must press the down arrow next to the compile button. Doing this will reveal a drop down menu that let you choose the program type: 12 Chapter 1. Parts of the documentation:

17 1.3.5 Run a compiled program Press F5 or click the run button (inside the editor) to run the file. The program will run in the Output window which is interactive (support for stdin has been tested and works with the ACCEPT keyword) Getting started 13

18 Note: It will recompile the file and all its dependencies before running the compiled program Calculate the offset of a selected record Since version 2.2, you can now calculate the offset of a selected record. select the text that contains the record you re interested in, right click on the editor to open the context menu click Calculate PIC offsets. a new side panel will open and will show you a table with the offset of each selected record: 14 Chapter 1. Parts of the documentation:

19 1.3.7 Switching to a full dark style Since version 2.2, OpenCobolIDE comes with a dark style sheet. To activate it, open the preferences dialog (edit->preferences). Then go to the style page and click on the Dark style radio button Getting started 15

20 Your IDE shoul look like that: 16 Chapter 1. Parts of the documentation:

21 1.4 FAQ ) Where are the generated binaries? The executable program or module can be found in the bin folder next to your source file ) I cannot compile on Windows, the compiler freeze or I get a execution error. What can I do? First ensure that you do not have a conflicting installation of MinGW in your PATH. If yes, remove it. If the problem persists, do not hesitate to open an issue but OpenCobolIDE is known to work on Windows (from Xp, to 8). Chances are that the issue come from your configuration ) Cannot detect OpenCobol compiler on Mac OSX. What can I do? If you installed the open cobol compiler in a non-standard path, you will have to tell OpenCobolIDE where to look FAQ 17

22 You can specify the path to the compiler in the preferences dialog (Build & Run tab) ) Is it possible to install from source on Windows or Mac OSX? Installation from source is possible on Mac and Windows: install all requirements (Python3, PyQt5, pyqode.core) run the open-cobol-ide script from the extracted archive or git repository without actually installing Open- CobolIDE. Do not run setup.py install on Windows or Mac OSX, it won t work. 1.5 Contributing OpenCobolIDE is an open-source project, and it needs your help to go on growing and improving. You can contribute in many different ways: reports new bugs/features on the issue tracker fork the project and send pull requests to merge your work If you have any question, just open an issue on the issue tracker Recommendation for submitting a bug report: To submit a valuable bug report, the following information is required: Operating System Desktop Environment (for GNU/Linux only) Describe the way you installed the IDE (for GNU/Linux only): pip or apt-get or another method? Include the Application log output content (Menu->View->Application log->show window) Recommendation for submitting a Pull Request: Pull Requests are great (on the dev branch)! Readme/Documentation changes are ok in the master branch. Fork the Repo on github. Push to your fork and submit a pull request to the dev branch. The master branch is used for the stable releases, following the git workflow. Please use PEP8 to style your code. 1.6 License OpenCobolIDE is licensed under the GPL v3. What s New? What s new since the last release, and what is planned for the next one. Download & Install Instructions on where and how to install pyqode. Getting started Getting started with OpenCobolIDE FAQ Frequently asked questions 18 Chapter 1. Parts of the documentation:

23 CHAPTER 2 Meta information: Contributing How to contribute and report bugs License OpenCobolIDE license 19

24 20 Chapter 2. Meta information:

25 CHAPTER 3 Indices and tables: genindex search 21

26 22 Chapter 3. Indices and tables:

27 CHAPTER 4 Disclaimer I am by no way a cobol expert, I just had to work on a cobol project at my night school with an awful IDE (NetExpress on a Windows Xp virtual machine). As I was writing pyqode (a code editor widget for python qt applications), I thought it would be the perfect occasion to show what pyqode can do and write a simple and lightweight cobol IDE that I could run on my favorite Linux distribution I ve only learned COBOL 74 and the IDE has been designed with this standard in mind. I have no plan on working with cobol at the moment nor to learn a new standard but if you found a missing feature, feel free to open a feature request. I m always looking forward to make OpenCobolIDE better. Your advice is needed and will be very appreciated! 23