-------------------------------------------------------------------------------
Build.

Make sure you've built with debug info:

  cd ~/openairinterface5g # or wherever
  source oaienv
  cd cmake_targets
  ./build_oai --UE --eNB --verbose-compile --run-with-gdb RelWithDebInfo
  make -C ran_build/build -j4 lte-softmodem lte-uesoftmodem

-------------------------------------------------------------------------------
Verify.

Verify the build was done correctly:

$ ./gdb-helper
...
Reading symbols from ./ran_build/build/lte-softmodem...done.
(gdb) b main
Breakpoint 1 at 0x59f110: file /local/episys/openairinterface5g/targets/RT/USER/lte-softmodem.c, line 516.
(gdb) run
Starting program: /local/episys/openairinterface5g/cmake_targets/ran_build/build/lte-softmodem -O ../ci-scripts/conf_files/rcc.band7.tm1.nfapi.conf --noS1
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

Breakpoint 1, main (argc=4, argv=0x7fffffffe058) at /local/episys/openairinterface5g/targets/RT/USER/lte-softmodem.c:516
516     {
(gdb) list
511       pthread_mutex_unlock(&nfapi_sync_mutex);
512       printf( "NFAPI: got sync (%s)\n", thread_name);
513     }
514
515     int main ( int argc, char **argv )
516     {
517       struct sched_param param =
518       {
519         .sched_priority = 79
520       };
(gdb) n
521       if (sched_setscheduler( 0, SCHED_RR, &param ) == -1 )
(gdb) quit
A debugging session is active.

        Inferior 1 [process 19964] will be killed.

Quit anyway? (y or n) y
$

If gdb says "no debugging symbols found" then clean your workspace and re-do
the build as above.

(gdb) b main

-------------------------------------------------------------------------------
Password-less sudo.

Vscode launches lte-softmodem via sudo.  Make sure sudo does not prompt you
for a password:

  sudo -n id

If that command fails, do the following:

  echo "$USER ALL=(ALL) NOPASSWD: ALL" | sudo tee -a /etc/sudoers

Then verify:

  sudo -n id

-------------------------------------------------------------------------------
Vscode.

Launch Vscode:

  cd ~/openairinterface5g # or wherever
  code . targets/RT/USER/lte-softmodem.c .vscode/launch.json

See launch.json for details about how vscode launches lte-softmodem for debugging.

For example, in lte-softmodem.c, scroll to main() and click the line number to
the left of main to add a breakpoint.  then do Run => Start debugging (F5) to
run lte-softmodem in the debugger

-------------------------------------------------------------------------------
Running Vscode remotely.

Currently, running Vscode remotely (via an X-Windows connection) does not work
-- the Vscode window appears but remains blank.  Presumably the Vscode
developers will fix this problem eventually.  Meanwhile, you can use `sshfs`
to make the remote filesystem appear locally and then run Vscode locally.

On the local machine:

  $ remote=surfer      # or whatever the remote machine's name is
  $ mkdir ~/openairinterface5g
  $ sshfs $remote:openairinterface5g ~/openairinterface5g
  $ ls ~/openairinterface5g
   CHANGELOG.md    CONTRIBUTING.md   nfapi       openair3            targets
  ...
  $ code ~/openairinterface5g
  $

The remote and local pathnames of your openairinterface5g workspace should be
the same.  If they're different, use a symlink on the local machine to make
the remote pathnames work locally.  This part is important because executables
built on $remote contain references to the source files and vscode & gdb will
use those pathnames to find the source files.

You may want to locally mount the remote logs directory, too:

  $ mkdir ~/logs
  $ sshfs $remote:logs ~/logs
  $ ls -l ~/logs
  total 40
  lrwxrwxrwx 1 1002 1002   22 Jan 17 11:54 latest -> logs-2021-01-17-085419
  drwxr-xr-x 1 1002 1002 4096 Jan 17 11:54 logs-2021-01-17-085419
  $

That will give you access to core files collected by lte_testscript.py, for
example.

  $ file ~/logs/latest/0001/coredump-6699
  /home/michael/logs/latest/0001/coredump-6699: ELF 64-bit LSB core file,
  x86-64, version 1 (SYSV), SVR4-style, from './ran_build/build/lte-softmodem
  -O ../ci-scripts/conf_files/rcc.band7.tm1.nfapi', real uid: 0, effective
  uid: 0, real gid: 0, effective gid: 0, execfn:
  './ran_build/build/lte-softmodem', platform: 'x86_64'
  $
  $ file ~/openairinterface5g/cmake_targets/ran_build/build/lte-softmodem
  /home/michael/openairinterface5g/cmake_targets/ran_build/build/lte-softmodem:
  ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked,
  interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.32,
  BuildID[sha1]=831400d4aae5d43b94ef3b22ebbd635107de48ae, with debug_info, not
  stripped
  $

Verify gdb can access these remote files:

  $ gdb ~/openairinterface5g/cmake_targets/ran_build/build/lte-softmodem \
  ~/logs/latest/0001/coredump-6699
  ...
  Program terminated with signal SIGABRT, Aborted.
  #0  0x00007f7fd7d11438 in ?? ()
  [Current thread is 1 (LWP 39)]
  (gdb)

If this step is too slow, you may want to copy the executable and coredump
files to the local machine first.

  $ scp -C $remote:openairinterface5g/cmake_targets/ran_build/build/lte-softmodem .
  $ scp -C $remote:logs/latest/0001/coredump-6699 .
  $ gdb lte-softmodem coredump-6699

-------------------------------------------------------------------------------
