######################################################################################
## PLEASE NOTE: This version of the lldb-based debugger is being deprecated.        ##
##   Please try the Python-based traceRMI versions documented in the Debugger help. ##
######################################################################################

To use the LLDB agent in Ghidra, you will need to build the JNI interface to the LLDB Scripting Bridge.

If you are using the distribution (vs. source) and wish to use the default swig files included (LLDB v17), you can use the
macos_debugger_lldb_build_from_brew script in this same directory, kindly provide by @cyberkaida.  Make sure a 7.x version
of gradle is in your path, and you've defined GHIDRA_INSTALL_DIR.

To do this:
(1) check the version for your copy of lldb:
	lldb --version
	
If you have a version other than the most current (release/17.x), you will need to generate the JNI interface for the version you have.

(2a) To install LLVM/lldb version 17:
	- git clone https://github.com/llvm/llvm-project.git
	- cd llvm-project
	- git checkout release/17.x
	
IF YOU WISH TO BUILD LLDB:
	- cd llvm-project
	- mkdir build && cd build
	- cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;lldb" -DCMAKE_BUILD_TYPE=Release -DLLDB_INCLUDE_TESTS=off ../llvm
	(on macos, you may also want to include -DLLDB_CODESIGN_IDENTIY="lldb_codesign")
	- ninja lldb
	- ninja lldb-server
	- ninja install
	
(2b) To generate the JNI for your version
	- cd Ghidra/Debug/Debugger-swig-lldb
	- gradle generateSwig
	- cp -r build/generated/src/main src
	- If you are using the source (vs. a distribution), delete build/generated/src/main afterwards.

If you have the most current version or have completed step (2), you can:

(3) Compile the JNI interface by:
	- export JAVA_HOME=/path_to_java
	- export LLVM_HOME=/path_to_llvm-project
	- export LLVM_BUILD=/path_to_llvm_build_directory_or_whatever_contains_lib/liblldb.(so/dylib/dll)
	 (for Windows, these vars should have the drive: prefix and probably not have spaces)
	 NB: If you have built lldb from source, you may need to "ln -s liblldb.x.x.x.so/.dylb liblldb.so/.dylib".
	- cd Ghidra/Debug/Debugger-swig-lldb
	- gradle build
	
(4) To run:
	- add -Djava.library.path=/path_to_liblldb:/path_to_liblldb-java:etc (not including the actual library name)
	  in support/launch.properties or, if you're running out of Eclipse, to the arguments in the Run/Debug Configuration
	  
TROUBLESHOOTING:
(1) If you are trying to execute "gradle buildGhidra" with LLVM_HOME already set, you are likely 
    to run into difficulties.  Unset LLVM_HOME (or on Windows set LLVM_HOME=) before running.
(2) If you are running "gradle generateSwig" and encounter errors, make sure LLVM_HOME is set.
(3) If you are running "gradle build" and it succeeds but there is no library in Ghidra/
    Debug/Debugger-swig/lldb/build/os, again check LLVM_HOME, LLVM_BUILD, and JAVA_HOME.  Keep
    in mind that different generators for LLVM, esp. for Window, may put liblldb.xxx in unusual 
    places. Check "build/lib", "build/bin", and subdirs like "build/Release/bin".
(4) If you get an "Unsatisfied Link Error" when you start the debugger,  make sure both liblldb
    and liblldb-java are in the path described by java.library.path.
(5) Link errors can also be caused by different architectures or platforms for the libraries.
(6) You may need to set up the development environment before running gradle:
		gradle -I gradle/support/fetchDependencies.gradle init
(7) If you are using the homebrew installation of lldb, you may need to modify build.gradle or 
    buildNatives.gradle to reflect the homebrew directory structure, 
    e.g. $llvm_dir/lldb/include -> $llvm_dir/include.
(8) If you are compiling on macos, make sure you are compiling only the versions supported by your 
    platform (by editing build.gradle or buildNatives.gradle).
(9) If you are running with a very current version of swig, e.g. 4.1 or later, you may have to:
	- edit llvm-project/lldb/bindings/interface/SBValueList.i and remove the two references to nothreadallow.
	- edit the build.gradle or buildNatives.gradle and remove -D__STDC_LIMIT_MACROS
	

    
    
    
