Scripting brings a powerful form of dynamic extensibilty to Ghidra, where Java source code is (re)compiled, loaded, and run without exiting Ghidra. When a script grows large or requires external dependencies, it @@ -17,7 +19,7 @@
To support modularity while preserving the dynamic nature of scripts, Ghidra uses OSGi. Without delving too much into terminology, the key things to know are
-+
- +
- The unit of modularity in OSGi is the bundle. Bundles are mostly independent components with declared imports and exports.
@@ -47,25 +49,34 @@
-When a directory is added to the Bundle Manager, it is treated as a source bundle. When enabled, its Java contents are compiled to +
<user home>/.ghidra/.ghidra-<version>/osgi/compiled-bundles/<hash>/+where
-<hash>is a hash of the source bundle path. These compiled artifacts are then loaded - by the OSGi framework.exploded bundles
+ by the OSGi framework. + + + +Exploded Bundles
+-Each such subdirectory of
compiled-bundles/is an exploded jar -- by compressing it, we get a standard OSGi Jar bundle:jar cMf mybundle.jar -C $HOME/.ghidra/.ghidra_<version>/osgi/compiled-bundles/<hash> .+generated files
+Generated Files
++If there is no manifest in the source directory, Ghidra generates one using bndlib so that:
@@ -77,13 +88,17 @@If no bundle activator is present, a stub is created and referenced in the generated manifest.
+
Two types of code dependency are available when developing with OSGi, intra-bundle and inter-bundle.
-intra-bundle (compile time) dependency
+Intra-bundle (compile time) Dependency
+-Classes within a bundle, e.g. source files in a source bundle, can rely one another with Java's usual package
import.This kind of dependency is resolved at compile time -- if a class isn't imported or present, compilation will fail.
@@ -115,8 +130,10 @@ } } +inter-bundle (run time) dependency
+Inter-bundle (run time) Dependency
++To make use of code from other bundles, a bundle must declare its dependencies. When a bundle is activated, the framework attempts to resolve its declared dependencies against active bundles. The @@ -128,6 +145,7 @@ resolution.
+
@importpackagein a scriptGhidra's
@@ -161,8 +179,10 @@ } } +@importpacakgemeta-data tag provides a convenient way to declare inter-bundle dependencies directly in a script. Set the value to a comma separated list of packages to import from other bundles.+
Import-Packagein the manifest+The underlying OSGi mechanism for declaring inter-bundle dependency is via the manifest.
You can find detailed descriptions of manifest attributes used by OSGi, like
Import-Package, here @@ -186,7 +206,10 @@ Bundle-Name: ab12cd89 Bundle-Activator: GeneratedActivator + +The manifest generated for
your_ghidra_scriptsis as follows: +<user home>/.ghidra/.ghidra-<version>/osgi/compiled-bundles/ef34ab56/META-INF/MANIFEST.MF: Manifest-Version: 1.0 @@ -204,9 +227,12 @@For full control, users can include a manifest with their bundle's source, e.g.
- +my_ghidra_scripts/META-INF/MANIFEST.MF.
For a bundle's contents to be available (e.g. for loading classes), its OSGi state must be "
ACTIVE". Ghidra generally takes care of this, but @@ -224,7 +250,7 @@The color of each bundle path reflects state as follows:
- +
- error - e.g. the bundle file is missing -
- disabled - Ghidra knows the +
- disabled - Ghidra knows the path, but that's it
- inactive - scripts are visible in the script manager, but no classes are loaded. A bundle moves into this state when its @@ -243,17 +269,19 @@
- (UNINSTALLED) - if the bundle is enabled, but the framework has released its handle. This is typical for an inactive bundle
Adding a directory to the bundle manager will also enable it, so scripts within become available in the script manager.
Removing a bundle disables it, so its scripts will be removed from the script manager and its dependents will become inactive.
- +
When Ghidra builds a source bundle, the results are written to the directory
<user home>/.ghidra/.ghidra-<version>/osgi/compiled-bundles/<hash>.
@@ -265,13 +293,23 @@If a source bundle's imports aren't available during build, some source files can produce errors. In order to force Ghidra to recompile, one must either modify the files with errors or clean the bundle then re-enable.
+
+ +Refresh will deactivate, clean, then reactivate every enabled bundle.
+
+