The following summarizes our experience of using Eclipse IDE for developing ADDA. Hopefully, some of the information may be useful for other IDEs as well. Surely, we do not suggest that Eclipse is, in any sense, the best IDE, but it does fulfill our needs. Moreover, any IDE works on top of standard console compilation of ADDA, which need to be set up separately.

• Basic installation
• Build and launch configurations
  • Build targets
  • Advanced build configurations
  • Launch configurations
• Interaction with git
• Editor settings
  • Main code
  • Bash scripts
  • Wiki pages

Install Eclipse IDE for C/C++ Developers (CDT) from Downloads (first, get installer). It includes git integration (Egit) and WikiText editor plugin. Eclipse IDE for Scientific Computing also looks suitable (additionally includes tools for Fortran, MPI, and OpenMP), but we haven't tried it. The following is based on version 2019-03 (where it was thoroughly tested). But certain changes were required for version 2021-12, thus, several actions below need to be performed only for specific (and similar) Eclipse versions - they are marked by the corresponding version numbers.

If upgrading, choose an existing workspace at the runtime (the project will appear automatically with most settings). Otherwise, create a new workspace and do the following:

• File –> New –> Makefile project with existing code
• Set project name ("ADDA" is assumed in the following), path to the top folder of ADDA (e.g. produced by git clone), and choose compiler (GCC in general, for Windows - "MinGW GCC" that should be separately installed)

Eclipse have build configurations, build targets, and launch (run/debug/profile) configurations. To create the first operational build configuration, get into Project Properties. For that select the project (any folder) in Project Explorer (to the left) and in the top menu Project -> Properties. Alternatively, select top folder of the project and press Alt + Enter. There, starting from the left menu:

• C/C+ Build -> Tool Chain Editor -> (main window) -> Current Builder -> Gnu Make Builder
• C/C++ Build -> (main window) ->
  • Manage Configurations... -> rename Default into seq (optional)
  • Builder Settings -> (sub-window) ->
    • (v. 2019-03) Use default build command -> uncheck
    • (v. 2019-03) Build command -> make -s OPTIONS=DEBUG (silent unless errors, and leave debugging symbols to use internal Eclipse capabilities)
    • Makefile Generation -> Generate makefiles automatically -> uncheck
    • Build location -> Build directory -> ${workspace_loc:/ADDA/src} or select path to src/ folder after pressing Workspace... or "File system...".
  • Behavior -> (sub-window) ->
    • (v. 2021-12) Use custom build arguments -> uncheck
    • (v. 2021-12) Build arguments -> -s OPTIONS=DEBUG
    • Build (Incremental Build) -> seq (optional)

Here and further, when updating settings, do not forget to apply them - look for buttons "Apply" or "Apply and Close".

Build targets are easy to set and is recommended as the first step. They can be created by right-clicking on the project name in Project Explorer (to the left) - Build Targets -> Create. However, we recommend:

• Go into the sub-menu Build Targets to the right (near Outline).
• Right click on folder src/ -> New... , input seq into the Target Name, leave everything else checked and press OK.
• Repeat for other build targets (mpi, ocl, clean, cleanseq, cleanmpi, cleanocl. You can now click on the build targets to have three basic compilation regimes of ADDA with make options set above (although this build configuration is called seq). clean... targets are the first to try if something weird is happening during the compilation.

Similarly, you can make build targets in misc folder (for example, for misc/hyperfun, misc/near_field, and misc/pip). For that:

• Right click on the corresponding folder -> New...
• Target Name -> all
• Build command ->
  • Use builder settings -> uncheck
  • Build command -> make
• Press OK If you're interested in compiling only ADDA itself, right click on src/ -> Go Into. You will see only the build targets for this folder. Similarly "Go Into" can be used in Project Explorer to limit oneself to src/ folder.

Additional build configurations are important, if you want to change compilation parameters, in particular, those given in OPTIONS=... argument to make. To create a new one, choose "Manage Configurations..." (see above) -> New... -> Copy settings from -> Existing configuration. Then review the new configuration; in most cases, you will only need to change "Build command" after OPTIONS=. The possible options include

• DEBUGFULL (for using ADDA internal debugging)
• "DEBUG FFT_TEMPERTON" (to use built-in FFT)
• remove OPTIONS= to make release configuration. But that doesn't make a lot of sense, since Eclipse will be almost useless in debugging it due to high-level optimizations. So releases are better made with bash scripts.

For advanced compiling it is convenient to make three build configurations (seq, mpi, ocl) for each set of OPTIONS=. They would differ only by name (e.g., debug_seq, debug_mpi, debug_ocl) and "Build (Incremental Build)" (optional steps above). This will make build targets largely unnecessary (except for clean... ones) - you will be able to select both make options and build targets from a single (but crowded) list of build configurations. Look for adjacent clock and hammer icons in the middle of the row above the main window. The clock (and its drop-down menu) can be used to switch configurations, the hammer - to switch and build with one click. Importantly, such (incremental) build configuration can be associated with launch configuration (unfortunately, it is not possible to separately associate build target with the latter).

The build configurations can also be used to tune the code indexer to properly recognize, which parts of the code are operational based on specific preprocessor directives. Note, however, that this will cause the index to be rebuilt on each change of configuration (may take several seconds). For that:

• Project -> Properties -> C/C+ General ->
  • Indexer ->
    • Either (due to an existing bug, this option will not be saved):
      • Enable project specific settings
      • Build configuration for the indexer -> Use active build configuration
    • or do the same for the whole workspace (then it is saved):
      • Configure Workspace Settings... -> Build configuration for the indexer -> Use active build configuration
  • Preprocessor Include Paths, Macros etc. -> (repeat for each) Configuration: -> Entries -> GNU C -> CDT User Setting Entries -> Add
    • Include Directory (and check "Contain system headers") - to locate header files. This is not needed if all library-header paths are specified in the gcc internal settings, like described for MinGW. The only exception is the path to Microsoft MPI headers on Windows. In the latter case add Include Directory ${MSMPI_INC} to all MPI configurations.
    • Preprocessor Macro - like ADDA_MPI, OPENCL, SPARSE, FFT_TEMPERTON (leave Value empty)

To create launch configuration select in top menu Run -> Run Configurations ... -> C/C++ Application -> Icon "New launch configuration" on the top left. We recommend to create three configurations: "adda", "adda_mpi", and "adda_ocl" differing by the executable file and run sequence. Inside the setting window update the following (remove .exe if not on Windows):

• adda
  • C/C++ Application -> src/seq/adda.exe
  • Build Configuration -> seq
  • Arguments ->
    • Program arguments -> ... (Update as needed)
    • Working directory -> ${workspace_loc:ADDA/src/seq}
• adda_mpi
  • C/C++ Application -> Browse... -> locate mpiexec, e.g., C:\Program Files\Microsoft MPI\Bin\mpiexec.exe
  • Build Configuration -> mpi
  • Arguments ->
    • Program arguments -> -n 4 adda_mpi ... (use, e.g., 2 or 4 processes)
    • Working directory -> ${workspace_loc:ADDA/src/mpi}
• adda_ocl
  • C/C++ Application -> src/ocl/adda_ocl.exe
  • Build Configuration -> ocl
  • Arguments ->
    • Program arguments -> -gpu 1 ... (specify GPU number on systems with multiple GPUs, including those embedded into the CPU)
    • Working directory -> ${workspace_loc:ADDA/src/ocl}

This will enable one-click launch of three basic configurations. The drawback is that you have a single build configuration associated with the launch one. Surely, you can choose a different build configurations when needed following the above instructions, but this is inconvenient if done often (e.g, when you used a lot of build configurations as discussed above). In the latter case we recommend using "Build Configuration -> Use Active" for all launch configurations. Then you can change build configuration with the clock button and build/launch it with the corresponding button to the left (which appearance varies with the selection in the dropdown menu "Run/Debug/Profile"). However, the responsibility of using compatible launch and build configurations then lies with you. For instance, running adda_ocl with mpi build configuration does not make sense.

The above works perfectly for running ADDA and observing output in the console. Debugging also works graphically inside Eclipse (if you specified OPTIONS=DEGUG in build commands above). The latter implies -O1 or -Og optimization flags, which should not interfere with the debugging. If, however, you encounter any artifacts, you may try build configurations with DEBUGFULL. Profiling does not yet works out of the box (see #265).

Eclipse includes EGit, which allows basic git functionality. The files in the project tree, which differ from the previous committed revision, are marked by > before their names. In the right-click menu there are option folders "Team", "Compare With", and "Replace With", which allows, among others, to compare the file again any previous revision or to revert the changes.

There was a bug in interaction of EGit with Git for Windows (nonstandard location of config files). However, it was fixed by further development of Git for Windows. So if you're using the latest version of the latter, you should be safe.

It is recommended to add the following local ignores (Eclipse-specific) to the file .git/info/exclude in ADDA local repository

# Eclipse
/.cproject
/.project
/.settings/

ADDA postulates a certain code style, which can be automated with Eclipse. The easiest is to import a set of options from the configuration file. For that: Project -> Properties -> C/C+ General -> Formatter -> Import ... -> locate file

To set up user dictionary for spelling checks navigate: Window -> Preferences -> General -> Editors -> Text Editors -> Spelling -> User defined dictionary -> Browse... . Any name will do (e.g., userdic.txt, but it is recommended to place it inside workspace (not in Eclipse installation directory) to simplify Eclipse updates.

Makefiles scripts are edited in full power out of the box. For other bash scripts you need to install Bash Editor plugin, which also allows debugging of scripts. Eclipse will suggest it, once you open any .sh file, e.g., in devtools/. Unfortunately, this plugin associates itself automatically only with .sh files. For others it is recommended to create new content type Shell in Window -> Preferences -> General -> Content Types -> Content types -> Text -> Add Child ... (button to the right). In description of this content:

• File associations -> add all scripts without extensions, e.g., from devtools/ and tests/2exec/.
• Associated editors -> add "Bash Editor" as the first one.

Eclipse also includes integration with system terminals - can be opened in any folder (in Project Explorer): Right click -> Show in Local Terminal -> choose one. On Windows the list includes Terminal (cmd) and Git Bash. One can add "MSYS bash" to this menu through Window -> Preferences -> Terminal -> Local Terminal -> "Show In ..." Custom Entries -> Add... (analogously to the existing Git Bash).

Built-in WikiText works reasonably well for ADDA wiki pages (Markdown files), both for editing and preview, with a few caveats:

• ADDA uses UTF-8 for wiki pages (at least non-trivial ones). Thus, you need to specify it. Either:
  • Put file org.eclipse.core.resources.prefs into .settings/ or
  • Set options manually:
    • Right click on the wiki folder in project tree -> Properties -> Resource -> Text file encoding -> Other -> UTF-8
    • Do the same for README.md in the repository root folder.
• Validation fails for some internal links (do NOT enable it in Project->Properties->WikiText), still it shows some errors, when you open the corresponding files. The closest issue is marked as fixed, but some parts of it are not actually fixed.
• Some GitHub-flavored elements are not rendered correctly (e.g., complex tables). For that you may additionally install GFM viewer. It uses GitHub API to render pages, but internal links does not work unless you turn off the Online mode (button).

Another well-tested option under Windows is to use Notepad++ - see description.