How-To use the remote client for connecting to Linaro Forge

Objective

This 30-minute tutorial will show you how to use the remote client and connect to a compute node on Meluxina

• The objective of this 30-minute tutorial is to show how to:
  • Setup the client remote configuration
  • Prepare your code for debugging
  • Start debugging

Forge clients

• Forge remote clients are available for Windows, macOS, and Linux, allowing users to connect to Melusina's compute nodes via SSH from their local desktop. These clients enable you to debug, profile, edit, and compile files directly on the remote compute nodes. You can download the appropriate client version from the Forge download page and install it on your desktop or laptop.

• Ensure that the client version you install matches the exact version of Forge on the software set you plan to use.

For instance, if you plan to use Linaro-Forge/24.0.2, which is available in the env/staging/2023.1 stack, execute the following from a local x86/64 AMD/Intel-equipped machine in a terminal:

mkdir linaro_install && cd linaro_install
wget https://downloads.linaroforge.com/24.0.5/linaro-forge-24.0.5-linux-x86_64.tar
tar -xvf linaro-forge-24.0.5-linux-x86_64.tar --directory=$PWD
cd linaro-forge-24.0.5-linux-x86_64/
./installer
#proceed with the installation from the GUI that pops up
echo 'export PATH=$HOME/linaro/forge/24.0.5/bin:$PATH' >> ~/.bashrc
ddt #this should open a Linaro-forge ddt GUI window

• To set up the client for a debugging session, start the client and select "Configure..." from the "Remote Launch" menu.

• Create a new connection using the "Add" button and fill the configuration with the appropriate information. The following are the fields you have to fill in:

Fields:

• Connection Name: a reference name for the connection

• Host name: hostnames used by the ssh command (On Mac/Linux, Forge will automatically list the existing hostnames in your ~/.ssh/config file if you press the down-pointing arrow on the right). We recommend you to select login04 as hostname as this login node has the specificity to have the module commands available. Hence, your ~/.ssh/config file should contain an entry like:

Host meluxina04 
    Hostname login04.lxp.lu
    User YOURUSERNAME 
    Port 8822
    ForwardAgent no
    IdentityFile ~/.ssh/id_ed25519_mlux 
    ForwardX11 yes
    ForwardX11Trusted yes

• Remote Installation Directory: root folder of current Linaro Forge installed on Meluxina. In the case where you would use the Linaro-Forge module installed on Meluxina and do not know how to locate the Linaro, start an interactive session and type:

ml Linaro-Forge
echo $EBROOTLINAROMINFORGE  # this will give you the installation directory of Linaro

• Remote script: a script to perform the setup after the client is connected to the remote machine (here: $HOME/.allinea/remote-init)

$HOME/.allinea/remote-init

module --force purge
module load env/staging/2023.1
module load Linaro-Forge
echo "Looks like connecting to the remote machine from Linaro is working!"

• Private key: It is optional if Forge is using a ssh connection setup in you ~/.ssh/config file

• KeepAlive Packets: Check the box

• Interval: Interval for the keep alive packets

Getting a job on Meluxina

• Connect to Meluxina's login node

• Get an interactive job and load Linaro-Forge

Getting first an interactive job

# Request an interactive job
salloc -A [p200xxx-replace-with-your-project-number] -t 01:00:00 -q dev -p cpu --res=gpudev  -N1
# Load the same Forge version than the client version
module load env/staging/2023.1
module load Linaro-Forge/24.0.2-GCC-12.3.0

• Keep the hostname of the node assigned to you (i.e.,mel-xxxx) and go back to the client configuration. For instance, in the below example mel0059 has been allocated to use.

• Append the node hostname to the "Host name" field as follows

• Click on "Test Remote Launch". You should see the following:

• Close the client configuration and connect to the remote Forge instance

• Once connected, please go back to your terminal where you requested the interactive job

Debugging a small application

• Create a empty C/C++ file called hello_world.cpp

• Copy-paste the following C/C++ code

hello_world.cpp

#include <iostream>
#include <mpi.h>
#define SIZE 10

int main(int argc, char **argv) 
{
  MPI_Init(&argc, &argv);

  int world_size;
  MPI_Comm_size(MPI_COMM_WORLD, &world_size);
  int my_rank;
  MPI_Comm_rank(MPI_COMM_WORLD, &my_rank);

  std::cout << "hello world from process " << my_rank << " of " << world_size << std::endl;


  if(my_rank == 1 ){
    int* heap_alloc = new int[SIZE];
    // Initialize
    for(int i = 0; i <= SIZE; i++)
        heap_alloc[i]=0;

    delete[] heap_alloc;
  }

  MPI_Finalize();

  return 0;
}

• Load the OpenMPI module using the follwing command: module load OpenMPI/4.1.5-GCC-12.3.0

• Compile the C/C++ code using the -g flags: mpic++ -g hello_world.cpp -o hello_world.mpi

• Execute the ddt command with --connect: ddt --connect srun -n 8 ./hello_world.mpi. You should see a pop-up appearing in the remote client asking you to accept the request coming from the remote compute node.

• Once you accepted the request, another pop-up will open asking you to choose run options

• Check the "Memory Debugging Options" box and click on details

• Use the same options as depicted on the above screenshot

• Finally, run debugging

The debugging interface

• The following interface should appear on your screen

• Place a breakpoint at line 31 and press the play button

• The ddt debugger should warn you that you try to write after the end of the heap memory allocation

• Notice the warning before execution at line 21 which indicates you that you are accessing index 10 which is out of bounds