UsingEclipse

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
  • Code analysis
  • Bash scripts
  • Wiki pages

Basic installation

Install Eclipse IDE for C/C++ Developers (CDT) from Downloads (first, get installer). It includes git integration (Egit) and WikiText editor plugin. The following was tested for version 2021-12 and later for 2024-06. We use bold font for Eclipse components and various GUI menus; they are typically selected by mouse but many menus allow textual search as well. The code formatting is used for something that should be typed in manually, including paths and filenames.

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)

Build and launch configurations

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) →
    • Makefile Generation → Generate makefiles automatically → uncheck
    • Build location → Build directory → ${workspace_loc:/ADDA/src} or select path to src/ folder after clicking Workspace... or File system....
  • Behavior → (sub-window) →
    • Use custom build arguments → uncheck
    • Build arguments → -s OPTIONS=DEBUG (silent unless errors, and leave debugging symbols to use internal Eclipse capabilities)
    • 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

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 click 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
• Click 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.

Advanced build configurations

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
    • Index all variants of the specific headers → vars.h,fft.h,prec_time.h
  • Preprocessor Include Paths, Macros etc. → (repeat for each) Configuration: → Entries → GNU C → CDT User Setting Entries → Add...
    • Include Directory – 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. For the latter, repeat the following for all MPI configurations:
      • change Project Path to File System Path
      • Variables → MSMPI_INC (choose from a long list) → OK
      • Contains system headers
    • Preprocessor Macro – like ADDA_MPI, OPENCL, SPARSE, FFT_TEMPERTON and others used as OPTIONS to make (leave Value empty)

Launch configurations

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 8 adda_mpi ... (e.g., for 8 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).

Interaction with git

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.

Editor settings

Main code

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 to Window → Preferences → General → Editors → Text Editors → Spelling → User defined dictionary → Browse... . The easiest is to use the provided userdic.txt, placing it inside workspace (not in Eclipse installation directory) to simplify Eclipse updates

ADDA assumes ASCII encoding for all files, except Markdown (discussed below). To avoid warnings, set Project → Properties → Resource → Text file encoding → Other → US-ASCII. Alternatively, copy org.eclipse.core.resources.prefs into .settings/.

Code analysis

Eclipse CDT includes powerful static code analysis tools, which can be set using Project → Properties → C/C+ General → Code Analysis. The default option works fine, except Potential programming errors → No return (turn it off to avoid a lot of false warnings). On top of the default settings you may also enable Missing cases in switch, Missing default in switch, Returning the address of a local variable, Static variable in header file, Symbol shadowing from the block Potential programming errors, as well as Goto statement used, Lack of copyright information, and Nesting comments from the block Coding Style, and Security Vulnerabilities → Format String Vulnerability.

The issues found by code analysis are collected in the Problems window in the bottom pane (Alt+Shift+Q,X). There are a number of warnings for the files in cpp/, related to Apple clFFT routines, which we do not maintain. These warnings can be suppressed by going into Customize Problem... in the right-click menu. Then press Scope → Exclusion patterns: → Add... and type-in specific filename or a pattern like src/cpp/*.

The easiest way to set up code analysis is to copy the org.eclipse.cdt.codan.core.prefs into .settings/ and then check Project → Properties → C/C+ General → Code Analysis → Use project settings.

Bash scripts

Makefile 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 BusyBox bash (shipped with w64devkit) to this menu through Window → Preferences → Terminal → Local Terminal → "Show In ..." Custom Entries → Add... (analogously to the existing Git Bash). However, BusyBox shell doesn`t open in the specified folder (we do not understand why).

Wiki pages

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/ (as advised above) 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.