How to set up Eclipse for GLFPE under Debian Linux 17 Jul 2020 GLF ----------------------------------------------------------------------------------------- GLF does not personally use the Eclipse IDE to develop C/C++ projects, but has experimented with adapting the GLFPE sample source code tree to Eclipse. The Eclipse IDE has been popular for many years, especially for Java programming. It is free and readily available for both Windows and Linux. The program is fairly large as IDEs go, taking up over 200 Mb on 64-bit Linux, but it is familiar to many users and has powerful code completion features built in. The IDE incorporates the concept of workspaces as a collection of projects. GLF has found the program is adaptable to individual GLFPE projects due to its ability to import existing Makefiles. The workspace structure itself, however, makes it somewhat difficult to adapt to an external tree stucture of projects. GLF has found that, as is the case with Microsoft's VisualStudio Code (vscode), it is least confusing to treat workspaces as essentially synonymous with projects, and assume a single project per workspace, naming the workspaces to match the project source names. In the case of vscode, the OS by default associates with the workspace extension (*.code-workpace) with the vscode program. Tht makes it easy to invoke the IDE with a project, IF there is one project per workspace. Similarly, one may interactively specify a workspace when launching Eclipse, and if there is one project per workspace, then the program comes up ready to build that project. Ideally, GLF expects to put all project (therefore workspace) specifications into the same folders as project configuration files for other IDEs (*.dev for Dev-C++, *.vpj for VIDE, *.cbp for Code::Blocks). That way the same source code and executable is compiled no matter what the IDE used. However, that structure did not work in testing for Eclipse. For some unknown reason, if the workspace file is set into the same folder as the source code, or even a "eclipse-workspace" folder beneath it, Eclipse cannot resolve the location of projects and refuses to build. Eclipse seems to put hidden and arbitrary restrictions on where workspace configuration files may be located in the filesystem. The default (all project workspaces go into "eclipse-workspace" under the home folder) is not acceptable for distributing code such as GLFPE source to other users. It is most desirable for open distribution to have all project-related specifications carried with the source code itself, in the same tree structure, so a user of the IDE can find the project launcher associated with that source project. GLF experimented with various alternate locations inside and outside the source tree until a solution was found which allowed all projects to build. Code portability across OS and IDE platforms --------------------------------------------------- GLF tries to maintain code portability between Linux and Windows where possible, and free or open source IDEs portable to both platforms are preferred. The same compiler toolset is used for GLFPE projects regardless of the IDE used to edit source and/or launch a build operation. That way whatever build system is chosen by a user, the project should produce identical functionality to the same project built using another IDE. The (Gnu/Linux/Unix standard) GCC toolchain (on Windows the MinGW equivalents) and Gnu "make" system is assumed to exist and be configured correctly to build all C/C++ projects. In recent years an alternate cross-platform compiler toolchain "clang" has become widely available, but GLF has not used it for GLFPE projects. Except for (obsolete legacy) MS-DOS development (using proprietary Borland Turbo C), GLF projects rely on the cross-platform GCC and its kin. Of the IDEs used by GLF (so far Dev-C++, VIDE, Code:;Blocks, VSCode, and Eclipse), some use Gnu "make" and some use an internal proprietary build system. Dev-C++ (Windows only), VIDE, and Eclipse (as used by GLF) rely on Makefiles. Dev-C++ and VIDE work from their own plaintext project file formats and autogenerate Makefiles for use in the actual build process. Code::Blocks and VSCode use proprietary build systems with mutually incompatible project configuration formats. GLF has created batch converter programs to convert Dev-C++ (*.dev) or VIDE projects (*.vpj) to equivalent Code::Blocks (*.cbp) project format. GLF has tested configurations which allow all these IDEs to produce functionally identical software. Installing the Eclipse IDE on GLF custom Linux OS distributions (Debian Mate based) ----------------------------------------------------------------------------------- GLF has not at this writing developed or tested Eclipse projects for Windows. GLF uses a custom remix of Debian 10 Mate as a Linux OS platform for everyday development. Since the projects often specify components differently for Windows versus Linux, the project files for Linux projects cannot be assumed to work without modification on Windows. The Eclipse projects described below rely on a tedious process of manually initiated "Import" operatiions under Eclipse which would probably need to be repeated in entirety under Windows to port to that platform. Therefore the instructions below consider only use of Eclipse on Linux, using GLFPE sample source code optmized and tested for that platform. GLF has acquired a recently downloaded binary executable of the Ecipse IDE as a 64-bit Linux *.tar.gz archive package (Eclipse version 2020-03-R). GLF has tested it as installed in one of two locations in the filesystem: If the IDE application has been preinstalled within a Live Boot Linux remix distribution, it will be found under the /usr/share/eclipse folder, and a *.desktop application launcher will be preinstalled to /usr/share/applications. If the application is NOT preinstalled, the user may unpack the *.tar.gz archive downloaded from the Eclipse website into the ~/eclipse folder. Optionally, the user may create a symlink or desktop launche to point to the binary executable which is located at at ~/eclipse/eclipse. GLF projects have been designed to only require Gnu "make" (not "automake" or "configure", which more complicated external projects may use), and require only a single Makefile per project. (Some large external software may use multiple nested Makefiles, GLFPE does not). Makefiles for "make"-based projects may be hand-created, copied and pasted with edits from other projects, or autogenerated by some IDEs or even GLF-written conversion programs. Eclipse itself does not provide the Makefiles for projects ported to Eclipse. The source code and the Makefiles are assumed to already exist before the Eclipse project is created, since the GLFPE sample code has been imported manually into Eclipse workspace/project structures by GLF. GLF standard practice is to first build and test projects using VIDE, which creates a Makefile.v (or PROJECTNAME.vmk), which may be copied to "Makefile" for use by Eclipse. The current run of GLF-produced live boot OS images supporting the GLF Programming environment (GLFPE) have already built in all the necessary library and toolset support necessary to build all (many) of the C/C++ projects in the GLFPE sample source code tree. GLF typically develops such code for Linux using built in text editors and VIDE as a build system. The *.vpj VIDE project files are plaintext and easy to create and maintain, and VIDE autogenerates good Makefile.v files to support project builds. GLF by practice copies all working Makefile.v files to project-specific *.vmk files (named to match each project) to support batch scripting of automatic builds from the command shell. Source tree and Eclipse project source tree structure ------------------------------------------------------- By trial and error GLF has found the following structure to allow Eclipse to work: All source is located under a subfolder "src" under the user's home folder. Underneath "src" is a folder (currently v64_830) which contains the GLF C/C++ source tree. Parallel to that is another folder named "Eclipsews_v64_830", which contains a parallel tree with all the same subfolder names to identify projects using the same names for Eclipse that are used by other IDEs. The "eclipse-ws" folder is used to store ONLY the workspace configurations (under ".metadata" subfolders) for each named project (tree folder name). All project source code remains under the other (v64_830) folder. GLF organizes groups of similar projects under an overriding category folder. For example, src/v64_830/astro/sid-clk and src/v64-830/testlibs/GL_bounce contain the source files for those two projects. Many of the GLF source files refer to header files and link libaries found in the src/v64_830/clibrary folder, which contains copies of headers and *.a static library files compiled from source projects one more layer down under clibrary (e.g. src/v64_830/clibrary/06_gflib). By design almost all *,c and *.cpp fles are found two layers down below "v64_830". Therefore most projects may use the relative reference "../../clibrary" to include headers and link libraries. There are helpful guides built into the program to assist such importation. One may launch Import under the File menu, or if a workspace/project is newly created, after closing the Welcome Screen a menu is presented which allows importing a project from an existing Makefile. The Gnu make program allows a Makefile to have any name if the name is specified on the command line, and GLF practice is to maintain tested Makefiles by copying or renaming them to a *.vmk file containing the project name. However, the Eclipse makefile import feature REQUIRES a file named "Makefile", and will look for no other name. Therefore, GLF has prepared the existing source tree by copying all working *.vmk files to a redundant copy named "Makefile" in each relevant source folder. These need to be maintained as a matching pair (if the underlying project is altered using another IDE, copy *.vmk to Makefile again). A correctly imported project cretes a .settings folder as well as a .cproject or .cppproject file and a .project file under the same foldwer as the original source files. This reliance on one project per workspace with all projects using identically named config files (.project, .cproject) causes the same organizational problem for Eclipse that is similarly caused by VSCode. Since all projects in a folder expect the same name for part of their specs, only one project may reside per folder, or else only one project's data will "stick", with others overwritten. The current GLFPE sample source tree has several folders which might cntaing multiple project specifications. Other IDEs used by GLF do not have this problem, in that the project files are uniquely named to match projects, so there are no conflicts. Thertefore, as of this writing not all GLFPE projects may be correctly adapted without further file tree organization to disambiguate the project configurations. Most GLFPE projects however adhere to one project per folder and are currently adaptable. In summary, upon correct installation of the GLF tested Eclipse IDE, there should be: A folder ~/eclipse containing the executable and its support files; A folder ~/src containing two subfolders, ~/src/v64_830 and ~/src/Eclipsews_v64_830; The folder v64_830 should contain category folders and project subfolders with all project source code and project spec files; The folder Eclipsews_v64_830 should contain the same folder names found in the same structure as under v64_830, but the folders should be empty except for ".metadata" folders containing workspace configurations (one per project). Each source code project folder, in addition to the project code modules and the Eclipse project specifications, must have an associated Makefile which Eclipse can use to build the project. The Makefile is not actually produced by Eclipse, so it must be maintained externally or generated by another build system (such as VIDE). In use, Eclipse creates several hidden side effect configuration folders (~/.eclipse, ~/.cache/Eclipse, etc.). However, if the source tree has been prepared properly (.settings subfolder, .cproject and .project files per source project folder, with matching workspace folders and structure in a separate subtree), the user need not copy any installed or modified home folder (user data) program configurations from prior runs when newly installing Eclipse for use with prepared GLFPE projects. The raw install of Eclipse will reconfigure these as it encounters prepared workspaces and builds projects. The necessary conversion of existing GLFPE projects (normmally created using VIDE) into Eclipse projects is not easily automated. The Eclipse workspace data structures are somewhat cryptic and too dependent on hidden data to be practical to simply convert from VIDE project specs by custom C program (as has been done for Code::Bocks). The most straightforward way to convert a VIDE project to an Eclipse project is a manual process described in the section below. To repeat the above for the approximately 700 projects in the GLFPE sample source tree is tedious at best and takes several days to accomplish. Because of this, GLF is in process of developing an automted script to perform the above steps on every project in the source tree without human intervention using "xdotool". This is not currently working well enough to let run by itself. It has tendency to "get lost" by trying to enter the wrong text into the wrong window at the wrong time, which creates chaos and stalls the automation. It usually works for a few projects then stalls. This is Work In Progress and will be developed over time. Since GLF does not personally use Eclipse for everyday work, it is a low priority project. A number of VIDE projects have been successfully converted to Eclipse projects using the above manual method and are included as part of the GLFPE sample souce tree. The freshly installed Eclipse IDE should readily handle these prebuilt GLFPE projects as previously defined in the workspace and source trees. An experienced user of a prior permanent installation of Eclipse should be able to successfully try out the workspaces/projects in the GLFPE tree without adversely affecting any existing work stored elsewhere in the filesystem. Using Eclipse with GLFPE sample source code to build an existing project ------------------------------------------------------------------------- As described above, GLF assumes one project per workspace. A set of workspace files which match the GLF tree structure and project naming conventions has been manually built, one project at a time, by importing existing working makefiles into Eclipse. Currently, the GLFPE C/C++ source tree is assumed to be under ~/src/v64_830 (assumes VIDE projects, 64-bit code, and GCC 8.30). The corresponding set of Eclipse workspace specifications is assumed to be in a parallel folder tree under ~/src/Eclipsews_v64_830. that folder has a subfolder to match names of every subfolder in the source tree dothe user may find the appropriate workspace for each project. However, the workspace folders contain ONLY the .metadata folders containing the Eclipse workspace definitions. For arcane reasons not fully understood by GLF but verified by experiment, Eclipse does not work if the workspace definitions are in the same folders as the source code. This structure is a manageable compromise which maintains project identities and organization while allowing Eclipse to build the projects. The user should consider each project as a separate workspace, and close/relaunch the Eclipse IDE each time a different workspace/project is selected. Assume a VIDE project exists in the ~/src/v64_83 source tree which has a *.vpj project file. Upon initial launch of Eclipse, the program requests the folder containing the desired workspace specification. Use the Browse button to bring up an explorer window and select the folder under ~/src/Eclipsews_v64_830 for the desired project. 1) Optionally build the project using VIDE to verify it builds properly. This process creates a Makefile.v file. GLFPE projects built from automated scripts usually copy Makefile.v to a project-specific *.vmk file. 2) Copy the Makefile.v file (or the *.vmk file) to a file in the same folder named "Makefile" (no extension). 3) Ensure there is a folder in the ~/src/Eclipsews_v64_830 tree to match the source folder. 4) Bring up Eclipse and specify the folder described in (3) above. 5) Eclipse should show a welcome screen. Close it, and a menu should suggest "Create project from existing Makefile". Click it. Specify "Linux GCC Project", and specify the project source folder and the project name (same as source folder name). 6) Eclipse should create all the necessary structures to create a workspace with one project, and it should be possible to build the project at this time. Click Window, View, C/C++ Project, and the project outline should show on the left. Build by executing Project, Clean, and accept Clean All Projects. Then select Project, Build All. Watch the console to verify the "0 Errors" status of the build. 7) Shut down Eclipse when done. Add and build new project -------------------------- To add a new project in the GLFPE source tree to the Eclipse workspace tree, first use VIDE to develop the project. Verify the project compiles and that the Makefile.v (and/or copy to *.vmk) works as expected for that project. To prepare for Eclipse, copy the same makefile to "Makefile" in the same folder. After that, create a matching empty subfolder within the equivalently named tree location under ~/src/Eclipsews_v64_830. Launch Eclipse, select the new (empty) workspace folder just created above, and accept it. The program should continue to launch and the editor Window should display a Welcome Screen. Close the Welcome Screen, and a helper menu should appear (left) which suggests several options. Select the one which creates a makefile project from existing source code. Alternatively select File, Import to get to the same project description window. In the project description wondow, select 9highlight) Linux GCC project, then browse to the source folder under ~/src/v64_830 for the project. Drill down the tree until the actual source files are displayed, then select. Usually the helper menus will go away and the project tree outline window will pop up. Test the build following the procedure for existing project above. Good luck and caveats ------------------------ Note that GLF still has no real intent to personally use Eclipse, but instead these structures and procedures have been built and tested to allow other interested users to readily adapt GLFPE source code to Eclipse if they would prefer to use Eclipse as IDE of choice. If users wish to alter or expand any of these projects, it is up to them to figure out how to do that. GLF only intends to help get interested users started. As usual, the GLFPE sample source code is presented as experimental example code, whether good or bad. No express or implied warranty attaches to its use or misuse by any person. The code is presented as-is. It may be poorly or inaccurately documented, erroneous in structure and/or performance, and it should be used only with caution. Some included programs may delete user data when used incorrectly or even correctly under unforeseen circumstances (be especially wary of programs under "dirs", which have a high potential for mischief).