GIPSPIN DOCUMENTATION (in-development) Getting Started Overview GIPSpin is a graphical interface programming system designed to provide the user with true visual programming. The user can see the flow of their code. Many additions for which graphical aids make sence to aid programming will be added as GIPSpin evolves and is enhanced. GIPSpin can output code in standard C++ format, and automatically "graphicalize" simple C code. Tutorials These samples can be found in “C:\Program Files\GIPSpin\examples” on Windows, and /usr/local/GIPSpin/examples on Linux. The tutorials are written with the Windows version in mind, but should be easy to follow on the Linux version as well. In the Linux version, to bring up a “New Library” you go the the “Edit” menu on top instead of the “Window” menu. "Hello World" On the top menu, select "Window"->"New Library". This should bring up a Library to allow you to select coding "Units" Let's make a "main" function now. Click on the "FUNCTION" Unit. Clicking on the name of the Unit is a good approach. This should have put a FUNCTION Unit in the upper left of your main window. Click to give focus to the top text entry (top white box in the Unit), and write "int" without the quotes. In the text entry below that write "main". Going back to the Library window change the top selection bar from "Function/Loops" to "Variables/Data". Click on the "PRINT" Unit. Move the "PRINT" Unit by clicking and holding the left mouse button down to give it some distance from the "FUNCTION" Unit. In the text entry of the "PRINT" Unit, enter with quotes "Hello World!". Now in the Library window go back to "Function/Loops" and select "END_FUNC" to indicate an end of function. Move "END_FUNC" to somewhere after the "PRINT" Unit. Now we link together the pieces. From the left option bar, select "Link". With the mouse, head towards the right side (output arrow) of the "FUNCTION" Unit. When it highlights, click the left mouse button. Now head towards the left side of the "Print" Unit. It should highlight when you get close to it. Press the left mouse button. You should now see a visual line linking the "FUNCTION" Unit to the "PRINT" Unit. Following a similar procedure, link together the "PRINT" Unit to the "END_FUNC" Unit. Now's a good time to save your work. In the top menu, select "File"->"Save to GIP". Save it to a file name of your choice. I recommend you give it the extension ".gip", but it is not enforced. If you installed MinGW, you can press "Run" from the left option bar, and in the DOS output window see your Hello World! Program run. You can also save you program to C++ and compile it the compiler of your choice. From the top menu, select "File"->"Save to C++" and save it with any name you choose. Simple Thread Customization Select “File”->”Options” from the top menu. You can add Compiler Options and set your favorite editor for “Data” Units. To set your editor you enter the executable in the “Editor” field. It will call that program whenever you Edit a “Data” Unit. (See Menu Details->Prefs for more details.) Gotchas/Defects 1) No anonymous structs in "Data" Units. Always typedef structs: typedef struct { int i; } mystructtype; Why? Because gcc does not allow pointers to anonymous structs which cause it to be very hard to pass data to a pthread-function when a user tries to do threading. 2) The "Print" Unit currently uses g++ "cout <<" functionality. If the variable is not one it recognizes it will not handle it correctly. 3) "Data" Unit can currently only handle C code. Why? Need to enhance my additions to GCC to handle parsing of C++ code. 4) You must close the Editor on “Data” Units for the changes to take effect. Why? The closing of the Editor is what triggers the re-read. This might be enhanced in the future so you do not have to do it if you use the default edit box. But if you use a custom editor, it will probably always be like that, since it is harder to interface with. 5)Core Dumps and functionality is still limited. Why? Sorry, GIPSpin is still a pre-alpha prototype. It will get better with time. Menu Details File Open File Supports the opening of GIP, C2XML, and simple C code files. GIP files are GIPSpin XML files created with "Save to GIP" and are the complete representation of the work represented in the GUI environment. C2XML files are XML files created using the c2xml program. This is automatically turned into a graphical representation. C is turned into XML format using C2XML and then handled as described above. Save to C++ Turns the current active window into C++ code. Save to GIP Saves the complete representation of the work represented in the GUI environment. Prefs Compiler Options These are the compiler options sent to mingw-gcc to compile and error check the code in GIPSpin. Editor You can set this to the binary of a custom editor for use with "DATA" Units. Example: Setting this to C:\emacs\emacs.exe will use emacs for editing code within "DATA" Units (assuming you have emacs at C:\emacs\emacs.exe). NOTE: You must close the editor after making your code changes in order for GIPSpin to know to pick up the changes. Quit Quits GIPSpin. NOTE: There is no warning/prompt to save work. Edit New Editor Opens up a new Editor window. Open Library Opens up a new Library allowing the selection of components. Cut Remove to the clipboard the banded selection. Copy Copy to the clipboard the banded selection. Paste Take the contents of the clipboard and paste it into the current active editor. Undo Undo the last operation. NOTE: Not all operations are supported yet. Most graphical operations are supported. No text changes are supported yet. Group Turn the banded selection into a Group Unit. View Errors Opens up the code error window for the current active editor. Help About Manual Flow Details Assembly/Analysis of Code The assembly of code is done in three stages- a pre-threading pass, followed by code analysis, followed by a final assembly. If there are no "THREAD" Units, the system is very simple and only the first step is performed. Internally in the code there is support for every Unit to create a C++ code representation by either adding to the beginning of the C++ file, append to the file as the Unit is visited, or adding to the end of the C++ file. Pre-threading (Flat) pass The starting point is the first found Unit with zero inputs. Then based on a simple traversal algorithm heavily dependent on the number of inputs/outputs of the Units, all the Units are visited. The "PRINT" Unit is an example of a Unit which causes "#include <iostream>" to be added to the beginning of the C++ file while at the same time adding "cout << var;" to the C++ file as it is visited. The "SWITCH" Unit is an example of a Unit which when it's "END_SWITCH" is visited, it traverses back to the "SWITCH" Unit to find the next "case" to traverse. The pass is called the "Pre-threading" pass since "THREAD" units are treated in a flat manner. The code between the "THREAD" and "END_THREAD" units are not encapsulated into pthreads; they are just laid out flat with markers in the C++ code for further code analysis. Code analysis To enable the encapsulation of code between the "THREAD" and "END_THREAD" units and for future enhancements to GIPSpin, a code analysis stage is needed. The "Flat pass" code is converted into an XML representation by C2XML. It is then analysed for variables between the "THREAD" and "END_THREAD" units. A data structure is created to hold this data for the Final assembly stage. Final assembly The variables between each "THREAD-END_THREAD" stage are passed to a custom made function which will be passed to pthread_create. The variables are passed as one C struct which contains pointers to each variable used. Within the custom made function, the pointer variables are de-referenced using C++ references and therefore code between the "THREAD-END_THREAD" can simply be inserted into the custom made function without needing further manipulation. Library Details Overview The Library contains pre-made Units for coding. Most of them are very familiar constructs recognizable to programmers. The creation of User defined and custom Units is in development. Components Function/Loops FUNCTION END_FUNC CALL FOR END_FOR WHILE END_WHILE DOWHILE END_DOWHILE Branch/Flow IF END_IF SWITCH END_SWITCH Variables/Data VARIABLE DATA INCLUDE Threads/Misc THREAD Allows code between "THREAD" and "END_THREAD" Units to be threaded through the use of pthreads. Line 1: Unique name for the "THREAD" Unit. NOTE: User must provide a unique name. Line 2...N: Unique name for each thread being created. NOTE: User must provide a unique name for each thread (within the context of this "THREAD" Unit). END_THREAD Unit to indicate the end of the "THREAD" unit. Custom1 Still not implemented. As you can imagine, the idea is to make your own boxes using either just Grouping of existing boxes or from code directly. This can be used to make pre-packaged algorithms. Development Status: We are at a Pre-Alpha stage. Basic functionality is implemented, but a lot of work remains to be done in bulletproofing the code, eliminating known defects/quick-fixes, and enhancements. Here's a list of known issues and TO-DO list: - Graphics cleanup Auto-refresh needs to be enhanced Unexpected events in multi-window support leading to crashes B-splice curves instead of lines - Code support Complex C structure support is limited leading to crashes C++ support Better support for complex projects (multiple files) Data-linkage support (variable/function finders) - Threading support More advanced algorithms to help users do special tasks - API An API interface to allow independent tools to make use of components - Command-Line programs Turn code dealing with XML<->C translation into separate command-line program |
|