hilda 2.0.2__py3-none-any.whl → 2.0.4__py3-none-any.whl

hilda/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.0.2'
-__version_tuple__ = version_tuple = (2, 0, 2)
+__version__ = version = '2.0.4'
+__version_tuple__ = version_tuple = (2, 0, 4)

hilda/cli.py

@@ -1,12 +1,14 @@
 import logging
 from pathlib import Path
-from typing import List, Mapping, Optional
+from typing import List, Optional
 
 import click
 import coloredlogs
 
 from hilda import launch_lldb
 from hilda._version import version
+from hilda.launch_lldb import create_hilda_client_using_attach_by_name, create_hilda_client_using_attach_by_pid, \
+    create_hilda_client_using_launch, create_hilda_client_using_remote_attach
 
 DEFAULT_HILDA_PORT = 1234
 
@@ -18,7 +20,7 @@ def cli():
     pass
 
 
-startup_files_option = click.option('-f', '--startup_files', multiple=True, default=None, help='Files to run on start')
+startup_files_option = click.option('-f', '--startup_files', multiple=True, help='Files to run on start')
 
 
 def parse_envp(ctx: click.Context, param: click.Parameter, value: List[str]) -> List[str]:
@@ -36,54 +38,58 @@ def parse_envp(ctx: click.Context, param: click.Parameter, value: List[str]) ->
 @click.argument('hostname', default='localhost')
 @click.argument('port', type=click.INT, default=DEFAULT_HILDA_PORT)
 @startup_files_option
-def remote(hostname: str, port: int, startup_files: Optional[List[str]] = None) -> None:
+def remote(hostname: str, port: int, startup_files: List[str]) -> None:
     """ Connect to remote debugserver at given address """
-    launch_lldb.remote(hostname, port, startup_files)
+    with create_hilda_client_using_remote_attach(hostname, port) as hilda_client:
+        hilda_client.interact(startup_files=startup_files)
 
 
 @cli.command('attach')
 @click.option('-n', '--name', help='process name to attach')
 @click.option('-p', '--pid', type=click.INT, help='pid to attach')
 @startup_files_option
-def attach(name: str, pid: int, startup_files: Optional[List[str]] = None) -> None:
+def attach(name: Optional[str], pid: Optional[int], startup_files: List[str]) -> None:
     """ Attach to given process and start a lldb shell """
-    launch_lldb.attach(name=name, pid=pid, startup_files=startup_files)
+    if name is not None:
+        hilda_client = create_hilda_client_using_attach_by_name(name)
+    elif pid is not None:
+        hilda_client = create_hilda_client_using_attach_by_pid(name)
+    else:
+        raise click.UsageError('You must specify a process name or pid')
+    hilda_client.interact(startup_files=startup_files)
+    hilda_client.detach()
+
+
+@cli.command('bare')
+def cli_bare() -> None:
+    """ Just start a lldb shell """
+    commands = [f'command script import {Path(__file__).resolve().parent / "lldb_entrypoint.py"}']
+    commands = '\n'.join(commands)
+    launch_lldb.execute(f'lldb --one-line "{commands}"')
 
 
 @cli.command('launch')
 @click.argument('exec_path')
 @click.option('--argv', multiple=True, help='Command line arguments to pass to the process')
 @click.option('--envp', multiple=True, callback=parse_envp, help='Environment variables in the form KEY=VALUE')
-@click.option('--stdin', type=str, help='Redirect stdin from this file path')
-@click.option('--stdout', type=str, help='Redirect stdout to this file path')
-@click.option('--stderr', type=str, help='Redirect stderr to this file path')
-@click.option('--cwd', type=str, help='Set the working directory for the process')
+@click.option('--stdin', help='Redirect stdin from this file path')
+@click.option('--stdout', help='Redirect stdout to this file path')
+@click.option('--stderr', help='Redirect stderr to this file path')
+@click.option('--cwd', help='Set the working directory for the process')
 @click.option('--flags', type=click.INT, default=0, help='Launch flags (bitmask)')
-@click.option('--stop-at-entry', is_flag=True, help='Stop the process at the entry point')
 @startup_files_option
-def launch(exec_path: str, argv: Optional[List] = None, envp: Optional[Mapping] = None,
-           stdin: Optional[Path] = None,
-           stdout: Optional[Path] = None, stderr: Optional[Path] = None, cwd: Optional[Path] = None,
-           flags: Optional[int] = 0, stop_at_entry: Optional[bool] = False,
-           startup_files: Optional[List[str]] = None) -> None:
-    """ Attach to given process and start a lldb shell """
-    if not argv:
-        argv = None
-    if not envp:
-        envp = None
-    launch_lldb.launch(exec_path, argv, envp, stdin, stdout, stderr, cwd, flags, stop_at_entry,
-                       startup_files)
-
-
-@cli.command('bare')
-def cli_bare():
-    """ Just start a lldb shell """
-    commands = [f'command script import {Path(__file__).resolve().parent / "lldb_entrypoint.py"}']
-    commands = '\n'.join(commands)
-    launch_lldb.execute(f'lldb --one-line "{commands}"')
+def launch(exec_path: str, argv: List[str], envp: List[str], stdin: Optional[Path],
+           stdout: Optional[Path], stderr: Optional[Path], cwd: Optional[Path], flags: Optional[int],
+           startup_files: List[str]) -> None:
+    """ Attach to a given process and start a lldb shell """
+    argv = list(argv)
+    envp = list(envp)
+    with create_hilda_client_using_launch(
+            exec_path, argv, envp, stdin, stdout, stderr, cwd, flags) as hilda_client:
+        hilda_client.interact(startup_files=startup_files)
 
 
 @cli.command('version')
-def cli_version():
+def cli_version() -> None:
     """Show the version information."""
     click.echo(version)

hilda/exceptions.py

@@ -1,7 +1,7 @@
 __all__ = ['HildaException', 'SymbolAbsentError', 'EvaluatingExpressionError', 'CreatingObjectiveCSymbolError',
            'ConvertingToNsObjectError', 'ConvertingFromNSObjectError', 'DisableJetsamMemoryChecksError',
            'GettingObjectiveCClassError', 'AccessingRegisterError', 'AccessingMemoryError',
-           'BrokenLocalSymbolsJarError', 'AddingLldbSymbolError', 'LLDBException', 'InvalidThreadIndexError']
+           'BrokenLocalSymbolsJarError', 'AddingLldbSymbolError', 'LLDBError', 'InvalidThreadIndexError']
 
 
 class HildaException(Exception):
@@ -9,12 +9,9 @@ class HildaException(Exception):
     pass
 
 
-class LLDBException(Exception):
-    """ A domain exception for lldb errors. """
-
-    def __init__(self, message: str):
-        super().__init__()
-        self.message = message
+class LLDBError(HildaException):
+    """ Wrapper for RAW LLDB errors """
+    pass
 
 
 class SymbolAbsentError(HildaException):

hilda/hilda_client.py

@@ -58,6 +58,7 @@ GREETING = f"""
 <b>Hilda has been successfully loaded! 😎
 Usage:
  <span style="color: magenta">p</span>   Global to access all features.
+ <span style="color: magenta">F1</span>  UI Show.
  <span style="color: magenta">F7</span>  Step Into.
  <span style="color: magenta">F8</span>  Step Over.
  <span style="color: magenta">F9</span>  Continue.
@@ -74,7 +75,7 @@ def disable_logs() -> None:
     logging.getLogger('parso.python.diff').disabled = True
     logging.getLogger('humanfriendly.prompts').disabled = True
     logging.getLogger('blib2to3.pgen2.driver').disabled = True
-    logging.getLogger('hilda.launch_lldb').disabled = True
+    logging.getLogger('hilda.launch_lldb').setLevel(logging.INFO)
 
 
 SerializableSymbol = namedtuple('SerializableSymbol', 'address type_ filename')
@@ -357,17 +358,19 @@ class HildaClient:
         if not self.process.Continue().Success():
             self.log_critical('failed to continue process')
 
-    def detach(self):
+    def detach(self) -> None:
         """
         Detach from process.
 
         Useful in order to exit gracefully so process doesn't get killed
         while you exit
         """
+        if not self.process.is_alive:
+            return
         if not self.process.Detach().Success():
             self.log_critical('failed to detach')
-        else:
-            self.log_info('Process Detached')
+            return
+        self.log_info('Process Detached')
 
     @stop_is_needed
     def disass(self, address: int, buf: bytes, flavor: str = 'intel',
@@ -398,30 +401,33 @@ class HildaClient:
 
         return self.symbol(module.ResolveFileAddress(address).GetLoadAddress(self.target))
 
-    def get_register(self, name) -> Symbol:
+    def get_register(self, name: str) -> Union[float, Symbol]:
         """
-        Get value for register by its name
-        :param name:
-        :return:
+        Get value for register by its name. Value can either be an Symbol (int) or a float.
+
+        :param name: Register name
+        :return: Register value
         """
-        register = self.frame.register[name.lower()]
-        if register is None:
+        register_value = self.frame.register[name.lower()]
+        if register_value is None:
             raise AccessingRegisterError()
-        return self.symbol(register.unsigned)
+        return self._get_symbol_or_float_from_sbvalue(register_value)
 
-    def set_register(self, name, value):
+    def set_register(self, name: str, value: Union[float, int]) -> None:
         """
         Set value for register by its name
-        :param name:
-        :param value:
-        :return:
+        :param name: Register name
+        :param value: Register value
         """
         register = self.frame.register[name.lower()]
         if register is None:
             raise AccessingRegisterError()
-        register.value = hex(value)
+        if isinstance(value, int):
+            register.value = hex(value)
+        else:
+            register.value = str(value)
 
-    def objc_call(self, obj, selector, *params):
+    def objc_call(self, obj: int, selector: str, *params):
         """
         Simulate a call to an objc selector
         :param obj: obj to pass into `objc_msgSend`
@@ -525,27 +531,32 @@ class HildaClient:
                     value = hilda.symbol(hilda.evaluate_expression(name))
                     log_message += f'\n\t{name} = {hilda._monitor_format_value(fmt, value)}'
 
-            if options.get('force_return', None) is not None:
-                hilda.force_return(options['force_return'])
-                log_message += f'\nforced return: {options["force_return"]}'
+            force_return = options.get('force_return')
+            if force_return is not None:
+                hilda.force_return(force_return)
+                log_message += f'\nforced return: {force_return}'
 
-            if options.get('bt', False):
+            if options.get('bt'):
                 # bugfix: for callstacks from xpc events
                 hilda.finish()
-                hilda.bt()
+                for frame in hilda.bt():
+                    log_message += f'\n\t{frame[0]} {frame[1]}'
 
-            if options.get('retval', None) is not None:
+            retval = options.get('retval')
+            if retval is not None:
                 # return from function
                 hilda.finish()
                 value = hilda.evaluate_expression('$arg1')
-                log_message += f'\nreturned: {hilda._monitor_format_value(options["retval"], value)}'
+                log_message += f'\nreturned: {hilda._monitor_format_value(retval, value)}'
 
             hilda.log_info(log_message)
 
             for cmd in options.get('cmd', []):
                 hilda.lldb_handle_command(cmd)
 
-            if not options.get('stop', False):
+            if options.get('stop', False):
+                hilda.log_info('Process remains stopped and focused on current thread')
+            else:
                 hilda.cont()
 
         return self.bp(address, callback, condition=condition, **options)
@@ -835,7 +846,7 @@ class HildaClient:
             raise ConvertingFromNSObjectError from e
         return json.loads(json_dump, object_hook=self._from_ns_json_object_hook)['root']
 
-    def evaluate_expression(self, expression) -> Symbol:
+    def evaluate_expression(self, expression: str) -> Union[float, Symbol]:
         """
         Wrapper for LLDB's EvaluateExpression.
         Used for quick code snippets.
@@ -845,8 +856,8 @@ class HildaClient:
             currentDevice = objc_get_class('UIDevice').currentDevice
             evaluate_expression(f'[[{currentDevice} systemName] hasPrefix:@"2"]')
 
-        :param expression:
-        :return: returned symbol
+        :param expression: Expression to evaluate
+        :return: Returned value (either float or a Symbol)
         """
         # prepending a prefix so LLDB knows to return an int type
         if isinstance(expression, int):
@@ -859,12 +870,12 @@ class HildaClient:
         options.SetTryAllThreads(True)
         options.SetUnwindOnError(self.configs.evaluation_unwind_on_error)
 
-        e = self.frame.EvaluateExpression(formatted_expression, options)
+        sbvalue = self.frame.EvaluateExpression(formatted_expression, options)
 
-        if not e.error.Success():
-            raise EvaluatingExpressionError(str(e.error))
+        if not sbvalue.error.Success():
+            raise EvaluatingExpressionError(str(sbvalue.error))
 
-        return self.symbol(e.unsigned)
+        return self._get_symbol_or_float_from_sbvalue(sbvalue)
 
     def import_module(self, filename: str, name: Optional[str] = None) -> Any:
         """
@@ -1044,7 +1055,7 @@ class HildaClient:
         ipython_config.InteractiveShellApp.extensions = ['hilda.ipython_extensions.magics',
                                                          'hilda.ipython_extensions.events',
                                                          'hilda.ipython_extensions.keybindings']
-        ipython_config.InteractiveShellApp.exec_lines = ["disable_logs()"]
+        ipython_config.InteractiveShellApp.exec_lines = ['disable_logs()']
         if startup_files is not None:
             ipython_config.InteractiveShellApp.exec_files = startup_files
             self.log_debug(f'Startup files - {startup_files}')
@@ -1052,10 +1063,17 @@ class HildaClient:
         namespace = globals()
         namespace.update(locals())
         namespace['p'] = self
+        namespace['ui'] = self.ui_manager
+        namespace['cfg'] = self.configs
         if additional_namespace is not None:
             namespace.update(additional_namespace)
         sys.argv = ['a']
         IPython.start_ipython(config=ipython_config, user_ns=namespace)
+
+    def __enter__(self) -> 'HildaClient':
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
         self.detach()
 
     @staticmethod
@@ -1169,3 +1187,11 @@ class HildaClient:
                 '__objc_class_list',
                 f'{objc_classlist_addr}')
             return json.loads(self.po(obj_c_code))
+
+    def _get_symbol_or_float_from_sbvalue(self, value: lldb.SBValue) -> Union[float, Symbol]:
+        # The `value` attribute of an SBValue stores a string representation of the actual value
+        # in a python-compatible format, so we can eval it to get the native python value
+        value = eval(value.value)
+        if isinstance(value, float):
+            return value
+        return self.symbol(value)

hilda/ipython_extensions/keybindings.py

@@ -6,7 +6,8 @@ from prompt_toolkit.keys import Keys
 def load_ipython_extension(ipython):
     def register_keybindings():
         hilda = ipython.user_ns['p']
-        keys_mapping = {Keys.F7: hilda.step_into,
+        keys_mapping = {Keys.F1: hilda.ui_manager.show,
+                        Keys.F7: hilda.step_into,
                         Keys.F8: hilda.step_over,
                         Keys.F9: lambda _: (hilda.log_info('Sending continue'), hilda.cont()),
                         Keys.F10: lambda _: (hilda.log_info('Sending stop'), hilda.stop())}

hilda/launch_lldb.py

@@ -4,7 +4,7 @@ from abc import ABC, abstractmethod
 from threading import Thread
 from typing import List, Optional
 
-from hilda.exceptions import LLDBException
+from hilda.exceptions import LLDBError
 from hilda.hilda_client import HildaClient
 from hilda.lldb_importer import lldb
 
@@ -14,14 +14,6 @@ lldb.hilda_client = None
 logger = logging.getLogger(__name__)
 
 
-def hilda(debugger, startup_files: Optional[List[str]] = None):
-    if lldb.hilda_client is None:
-        lldb.hilda_client = HildaClient(debugger)
-
-    additional_namespace = {'ui': lldb.hilda_client.ui_manager, 'cfg': lldb.hilda_client.configs}
-    lldb.hilda_client.interact(additional_namespace=additional_namespace, startup_files=startup_files)
-
-
 def execute(cmd: str) -> int:
     logging.debug(f'executing: {cmd}')
     return os.system(cmd)
@@ -49,10 +41,10 @@ class LLDBListenerThread(Thread, ABC):
     def _create_process(self) -> lldb.SBProcess:
         pass
 
-    def _check_success(self):
+    def _check_success(self) -> None:
         if self.error.Success():
             return
-        raise LLDBException(self.error.description)
+        raise LLDBError(self.error.description)
 
     def run(self):
         event = lldb.SBEvent()
@@ -67,7 +59,7 @@ class LLDBListenerThread(Thread, ABC):
                 logger.debug('Process Detached')
                 self.should_quit = True
             elif state == lldb.eStateExited:
-                logger.debug(f'Process Exited with status {self.process.GetExitStatus()}')
+                logger.info(f'Process Exited with status {self.process.GetExitStatus()}')
                 self.should_quit = True
             elif state == lldb.eStateRunning and last_state == lldb.eStateStopped:
                 logger.debug('Process Continued')
@@ -135,13 +127,12 @@ class LLDBLaunch(LLDBListenerThread):
     def __init__(self, exec_path: str, argv: Optional[List[str]] = None, envp: Optional[List[str]] = None,
                  stdin: Optional[str] = None,
                  stdout: Optional[str] = None, stderr: Optional[str] = None, wd: Optional[str] = None,
-                 flags: Optional[int] = 0, stop_at_entry: Optional[bool] = False):
+                 flags: Optional[int] = 0):
         self.exec_path = exec_path
         self.stdout = stdout
         self.stdin = stdin
         self.stderr = stderr
         self.flags = flags
-        self.stop_at_entry = stop_at_entry
         self.argv = argv
         self.envp = envp
         self.working_directory = wd
@@ -157,46 +148,40 @@ class LLDBLaunch(LLDBListenerThread):
         logger.debug(f'Lunching process  {self.exec_path}')
         return self.target.Launch(self.listener, self.argv, self.envp,
                                   self.stdin, self.stdout, self.stderr, self.working_directory,
-                                  self.flags, self.stop_at_entry,
+                                  self.flags, True,
                                   self.error)
 
 
-def remote(hostname: str, port: int, startup_files: Optional[List[str]] = None) -> None:
-    """ Connect to remote process """
-    try:
-        lldb_t = LLDBRemote(hostname, port)
-        lldb_t.start()
-        hilda(lldb_t.debugger, startup_files)
-    except LLDBException as e:
-        logger.error(e.message)
-
-
-def attach(name: Optional[str] = None, pid: Optional[int] = None, wait_for: bool = False,
-           startup_files: Optional[List[str]] = None) -> None:
-    """ Attach to given process and start a lldb shell """
-    if (name is not None and pid is not None) or (name is None and pid is None):
-        raise ValueError('Provide either a process name or a PID, but not both.')
-
-    try:
-        if name is not None:
-            lldb_t = LLDBAttachName(name, wait_for)
-        else:
-            lldb_t = LLDBAttachPid(pid)
-        lldb_t.start()
-        hilda(lldb_t.debugger, startup_files)
-    except LLDBException as e:
-        logger.error(e.message)
-
-
-def launch(exec_path: str, argv: Optional[List] = None, envp: Optional[List] = None,
-           stdin: Optional[str] = None,
-           stdout: Optional[str] = None, stderr: Optional[str] = None, wd: Optional[str] = None,
-           flags: Optional[int] = 0, stop_at_entry: Optional[bool] = False,
-           startup_files: Optional[List[str]] = None) -> None:
-    """ Launch to given process and start a lldb shell """
-    try:
-        lldb_t = LLDBLaunch(exec_path, argv, envp, stdin, stdout, stderr, wd, flags, stop_at_entry)
-        lldb_t.start()
-        hilda(lldb_t.debugger, startup_files)
-    except LLDBException as e:
-        logger.error(e.message)
+def _get_hilda_client_from_sbdebugger(debugger: lldb.SBDebugger) -> HildaClient:
+    hilda_client = HildaClient(debugger)
+    lldb.hilda_client = hilda_client
+    hilda_client.init_dynamic_environment()
+    return hilda_client
+
+
+def create_hilda_client_using_remote_attach(
+        hostname: str, port: int) -> HildaClient:
+    lldb_t = LLDBRemote(hostname, port)
+    lldb_t.start()
+    return _get_hilda_client_from_sbdebugger(lldb_t.debugger)
+
+
+def create_hilda_client_using_launch(
+        exec_path: str, argv: Optional[List] = None, envp: Optional[List] = None, stdin: Optional[str] = None,
+        stdout: Optional[str] = None, stderr: Optional[str] = None, wd: Optional[str] = None,
+        flags: Optional[int] = 0) -> HildaClient:
+    lldb_t = LLDBLaunch(exec_path, argv, envp, stdin, stdout, stderr, wd, flags)
+    lldb_t.start()
+    return _get_hilda_client_from_sbdebugger(lldb_t.debugger)
+
+
+def create_hilda_client_using_attach_by_pid(pid: Optional[int] = None) -> HildaClient:
+    lldb_t = LLDBAttachPid(pid)
+    lldb_t.start()
+    return _get_hilda_client_from_sbdebugger(lldb_t.debugger)
+
+
+def create_hilda_client_using_attach_by_name(name: Optional[str] = None, wait_for: bool = False) -> HildaClient:
+    lldb_t = LLDBAttachName(name, wait_for)
+    lldb_t.start()
+    return _get_hilda_client_from_sbdebugger(lldb_t.debugger)

{hilda-2.0.2.dist-info → hilda-2.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hilda
-Version: 2.0.2
+Version: 2.0.4
 Summary: LLDB wrapped and empowered by iPython's features
 Author-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>, netanel cohen <netanelc305@protonmail.com>
 Maintainer-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>, netanel cohen <netanelc305@protonmail.com>
@@ -55,34 +55,28 @@ Requires-Dist: inquirer3
 Provides-Extra: test
 Requires-Dist: pytest ; extra == 'test'
 
-- [Description](#description)
-- [Installation](#installation)
-- [How to use](#how-to-use)
-    - [Starting a Hilda shell](#starting-a-hilda-shell)
-        - [Attach mode](#attach-mode)
-        - [Launch mode](#launch-mode)
-        - [Bare mode](#bare-mode)
-        - [Remote mode](#remote-mode)
-            - [The connected device is connected via network](#the-connected-device-is-connected-via-network)
-        - [Startup Files](#startup-files)
-    - [Usage](#usage)
-    - [Magic functions](#magic-functions)
-    - [Shortcuts](#shortcuts)
-    - [Configurables](#configurables)
-        - [Attributes](#attributes)
-        - [Example Usage](#example-usage)
-    - [UI Configuration](#ui-configuration)
-    - [Symbol objects](#symbol-objects)
-    - [Globalized symbols](#globalized-symbols)
-        - [Searching for the right symbol](#searching-for-the-right-symbol)
-        - [Objective-C Classes](#objective-c-classes)
-    - [Objective-C Objects](#objective-c-objects)
-    - [Using snippets](#using-snippets)
-- [Contributing](#contributing)
-
-Would you like any further adjustments?
-
-# Description
+# Hilda
+
+- [Hilda](#hilda)
+  - [Overview](#overview)
+  - [Installation](#installation)
+  - [How to use](#how-to-use)
+    - [Starting a Hilda interactive shell](#starting-a-hilda-interactive-shell)
+    - [Inside a Hilda shell](#inside-a-hilda-shell)
+      - [Magic functions](#magic-functions)
+      - [Key-bindings](#key-bindings)
+      - [Configurables](#configurables)
+      - [UI Configuration](#ui-configuration)
+    - [Python API](#python-api)
+      - [Symbol objects](#symbol-objects)
+      - [Globalized symbols](#globalized-symbols)
+      - [Searching for the right symbol](#searching-for-the-right-symbol)
+      - [Objective-C Classes](#objective-c-classes)
+      - [Objective-C Objects](#objective-c-objects)
+      - [Using snippets](#using-snippets)
+  - [Contributing](#contributing)
+
+## Overview
 
 Hilda is a debugger which combines both the power of LLDB and iPython for easier debugging.
 
@@ -94,8 +88,8 @@ debugger-y" approach (based on LLDB).
 Currently, the project is intended for iOS/OSX debugging, but in the future we will possibly add support for the
 following platforms as well:
 
-* Linux
-* Android
+- Linux
+- Android
 
 Since LLDB allows abstraction for both platform and architecture, it should be possible to make the necessary changes
 without too many modifications.
@@ -105,14 +99,14 @@ Pull requests are more than welcome 😊.
 If you need help or have an amazing idea you would like to suggest, feel free
 to [start a discussion 💬](https://github.com/doronz88/hilda/discussions).
 
-# Installation
+## Installation
 
 Requirements for remote iOS device (not required for debugging a local OSX process):
 
-* Jailbroken iOS device
-* `debugserver` in device's PATH
-    * [You can use this tool in order to obtain the binary](https://github.com/doronz88/debugserver-deploy)
-    * After re-signing with new entitlements, you can put the binary in the following path: `/usr/bin/debugserver`
+- Jailbroken iOS device
+- `debugserver` in device's PATH
+  - [You can use this tool in order to obtain the binary](https://github.com/doronz88/debugserver-deploy)
+  - After re-signing with new entitlements, you can put the binary in the following path: `/usr/bin/debugserver`
 
 In order to install please run:
 
@@ -122,104 +116,40 @@ xcrun python3 -m pip install --user -U hilda
 
 *⚠️ Please note that Hilda is installed on top of XCode's python so LLDB will be able to use its features.*
 
-# How to use
+## How to use
 
-## Starting a Hilda shell
+### Starting a Hilda interactive shell
 
-### Attach mode
+You can may start a Hilda interactive shell by invoking any of the subcommand:
 
-Use the attach sub-command in order to start an LLDB shell attached to given process.
+- `hilda launch /path/to/executable`
+  - Launch given executable on current host
+- `hilda attach [-p pid] [-n process-name]`
+  - Attach to an already running process on current host (specified by either `pid` or `process-name`)
+- `hilda remote HOSTNAME PORT`
+  - Attach to an already running process on a target host (sepcified by `HOSTNAME PORT`)
+- `hilda bare`
+  - Only start an LLDB shell and load Hilda as a plugin.
+  - Please refer to the following help page if you require help on the command available to you within the lldb shell:
 
-```shell
-hilda attach [-p pid] [-n process-name]
-```
-
-### Launch mode
-
-Use the attach sub-command in order to launch given process.
-
-```shell
-hilda launch /path/to/executable \
-    --argv arg1 --argv arg2 \
-    --envp NAME=Alice --envp AGE=30 \
-    --stdin /path/to/input.txt \
-    --stdout /path/to/output.txt \
-    --stderr /path/to/error.txt \
-    --wd /path/to/working/directory \
-    --flags 0x01 \
-    --stop-at-entry
-  ```
-
-### Bare mode
-
-Use "Bare mode" to get a "bare-bones" lldb shell, whereas hilda plugin is already loaded and ready to start. This mode
-is useful when you need to have custom commands for attaching to the target process (for example when debugging OSX
-processes).
-
-To start this mode simply use:
-
-```shell
-hilda bare
-```
-
-Please refer to the following help page if you require help on the command available to you within the lldb shell:
-
-[lldb command map](https://lldb.llvm.org/use/map.html).
-
-As a cheatsheet, connecting to a remote platform like so:
-
-```shell
-platform connect connect://ip:port
-```
-
-... and attaching to a local process:
-
-```shell
-process attach -n proccess_name
-process attach -p proccess_pid
-```
-
-When you are ready, just execute `hilda` to move to Hilda's iPython shell.
-
-### Remote mode
-
-This mode will auto-connect to the remote device and attach to your target process assuming you are trying to debug a
-remote jailbroken iOS device.
-
-Please note the following:
-
-* script assumes the connected device already **has a running ssh server**, which doesn't require a password (you can
-  use
-  `ssh-copy-id` to achieve this).
+    [lldb command map](https://lldb.llvm.org/use/map.html).
 
-From this point the flow diverges into 2 flows:
+    As a cheatsheet, connecting to a remote platform like so:
 
-### The connected device is connected via network
+    ```shell
+    platform connect connect://ip:port
+    ```
 
-Run the following command:
+    ... and attaching to a local process:
 
-```shell
-hilda remote HOSTNAME PORT
-``` 
-
-## Startup Files
-
-Each command can accept startup files to execute on start. As opposed to snippets, the startup files can accept Hilda
-syntax.
-
-#### Startup File Example
-
-```python
-cfg.objc_verbose_monitor = True
-p.bp(ADDRESS)
-p.cont()
-```
+    ```shell
+    process attach -n proccess_name
+    process attach -p proccess_pid
+    ```
 
-```shell
-hilda remote HOSTNAME PORT -f startupfile1 -f startupfile2
-```
+    When you are ready, just execute `hilda` to move to Hilda's iPython shell.
 
-## Usage
+### Inside a Hilda shell
 
 Upon starting Hilda shell, you are greeted with:
 
@@ -232,52 +162,53 @@ Have a nice flight ✈️! Starting an IPython shell...
 Here is a gist of methods you can access from `p`:
 
 - `hd`
-    - Print an hexdump of given buffer
+  - Print an hexdump of given buffer
 - `lsof`
-    - Get dictionary of all open FDs
+  - Get dictionary of all open FDs
 - `bt`
-    - Print an improved backtrace.
+  - Print an improved backtrace.
 - `disable_jetsam_memory_checks`
-    - Disable jetsam memory checks, prevent raising:
+  - Disable jetsam memory checks, prevent raising:
       `error: Execution was interrupted, reason: EXC_RESOURCE RESOURCE_TYPE_MEMORY (limit=15 MB, unused=0x0).`
       when evaluating expression.
 - `symbol`
-    - Get symbol object for a given address
+  - Get symbol object for a given address
 - `objc_symbol`
-    - Get objc symbol wrapper for given address
+  - Get objc symbol wrapper for given address
 - `inject`
-    - Inject a single library into currently running process
+  - Inject a single library into currently running process
 - `rebind_symbols`
-    - Reparse all loaded images symbols
+  - Reparse all loaded images symbols
 - `poke`
-    - Write data at given address
+  - Write data at given address
 - `peek`
-    - Read data at given address
+  - Read data at given address
 - `peek_str`
-    - Peek a buffer till null termination
+  - Peek a buffer till null termination
 - `stop`
-    - Stop process.
+  - Stop process.
 - `cont`
-    - Continue process.
+  - Continue process.
 - `detach`
-    - Detach from process.
+  - Detach from process.
       Useful in order to exit gracefully so process doesn't get killed
       while you exit
 - `disass`
-    - Print disassembly from a given address
+  - Print disassembly from a given address
 - `file_symbol`
-    - Calculate symbol address without ASLR
+  - Calculate symbol address without ASLR
 - `get_register`
-    - Get value for register by its name
+  - Get value for register by its name
 - `set_register`
-    - Set value for register by its name
+  - Set value for register by its name
 - `objc_call`
-    - Simulate a call to an objc selector
+  - Simulate a call to an objc selector
 - `call`
-    - Call function at given address with given parameters
+  - Call function at given address with given parameters
 - `monitor`
-    - Monitor every time a given address is called
+  - Monitor every time a given address is called
       The following options are available:
+
       ```
       regs={reg1: format}
       will print register values
@@ -309,58 +240,57 @@ Here is a gist of methods you can access from `p`:
            override=True
                override previous break point at same location
       ```
+
 - `show_current_source`
-    - print current source code if possible
+  - print current source code if possible
 - `finish`
-    - Run current frame till its end.
+  - Run current frame till its end.
 - `step_into`
-    - Step into current instruction.
+  - Step into current instruction.
 - `step_over`
-    - Step over current instruction.
+  - Step over current instruction.
 - `remove_all_hilda_breakpoints`
-    - Remove all breakpoints created by Hilda
+  - Remove all breakpoints created by Hilda
 - `remove_hilda_breakpoint`
-    - Remove a single breakpoint placed by Hilda
+  - Remove a single breakpoint placed by Hilda
 - `force_return`
-    - Prematurely return from a stack frame, short-circuiting exection of newer frames and optionally
+  - Prematurely return from a stack frame, short-circuiting exection of newer frames and optionally
       yielding a specified value.
 - `proc_info`
-    - Print information about currently running mapped process.
+  - Print information about currently running mapped process.
 - `print_proc_entitlements`
-    - Get the plist embedded inside the process' __LINKEDIT section.
+  - Get the plist embedded inside the process' __LINKEDIT section.
 - `bp`
-    - Add a breakpoint
+  - Add a breakpoint
 - `show_hilda_breakpoints`
-    - Show existing breakpoints created by Hilda.
-- `show_commands`
-    - Show available commands.
+  - Show existing breakpoints created by Hilda.
 - `save`
-    - Save loaded symbols map (for loading later using the load() command)
+  - Save loaded symbols map (for loading later using the load() command)
 - `load`
-    - Load an existing symbols map (previously saved by the save() command)
+  - Load an existing symbols map (previously saved by the save() command)
 - `po`
-    - Print given object using LLDB's po command
+  - Print given object using LLDB's po command
       Can also run big chunks of native code:
 
       po('NSMutableString *s = [NSMutableString string]; [s appendString:@"abc"]; [s description]')
 - `globalize_symbols`
-    - Make all symbols in python's global scope
+  - Make all symbols in python's global scope
 - `jump`
-    - jump to given symbol
+  - jump to given symbol
 - `lldb_handle_command`
-    - Execute an LLDB command
+  - Execute an LLDB command
       For example:
       lldb_handle_command('register read')
 - `objc_get_class`
-    - Get ObjC class object
+  - Get ObjC class object
 - `CFSTR`
-    - Create CFStringRef object from given string
+  - Create CFStringRef object from given string
 - `ns`
-    - Create NSObject from given data
+  - Create NSObject from given data
 - `from_ns`
-    - Create python object from NS object.
+  - Create python object from NS object.
 - `evaluate_expression`
-    - Wrapper for LLDB's EvaluateExpression.
+  - Wrapper for LLDB's EvaluateExpression.
       Used for quick code snippets.
 
       Feel free to use local variables inside the expression using format string.
@@ -368,35 +298,37 @@ Here is a gist of methods you can access from `p`:
       currentDevice = objc_get_class('UIDevice').currentDevice
       evaluate_expression(f'[[{currentDevice} systemName] hasPrefix:@"2"]')
 - `import_module`
-    - Import & reload given python module (intended mainly for external snippets)
+  - Import & reload given python module (intended mainly for external snippets)
 - `unwind`
-    - Unwind the stack (useful when get_evaluation_unwind() == False)
+  - Unwind the stack (useful when get_evaluation_unwind() == False)
 - `set_selected_thread`
-    - sets the currently selected thread, which is used in other parts of the program, such as displaying disassembly or
+  - sets the currently selected thread, which is used in other parts of the program, such as displaying disassembly or
       checking registers.
       This ensures the application focuses on the specified thread for these operations.
 
-## Magic functions
+All these methods are available from the global `p` within the newly created IPython shell. In addition, you may invoke any of the exported APIs described in the [Python API](#python-api)
 
-Sometimes accessing the python API can be tiring, so we added some magic functions to help you out!
+#### Magic functions
+
+Sometimes accessing the [Python API](#python-api) can be tiring, so we added some magic functions to help you out!
 
 - `%objc <className>`
-    - Equivalent to: `className = p.objc_get_class(className)`
+  - Equivalent to: `className = p.objc_get_class(className)`
 - `%fbp <filename> <addressInHex>`
-    - Equivalent to: `p.file_symbol(addressInHex, filename).bp()`
+  - Equivalent to: `p.file_symbol(addressInHex, filename).bp()`
 
-## Shortcuts
+#### Key-bindings
 
 - **F7**: Step Into
 - **F8**: Step Over
 - **F9**: Continue
 - **F10**: Stop
 
-## Configurables
+#### Configurables
 
 The global `cfg` used to configure various settings for evaluation and monitoring.
 
-### Attributes
+These settings include:
 
 - `evaluation_unwind_on_error`: Whether to unwind on error during evaluation. (Default: `False`)
 - `evaluation_ignore_breakpoints`: Whether to ignore breakpoints during evaluation. (Default: `False`)
@@ -405,15 +337,9 @@ The global `cfg` used to configure various settings for evaluation and monitorin
 - `objc_verbose_monitor`: When set to `True`, using `monitor()` will automatically print Objective-C method arguments. (
   Default: `False`)
 
-### Example Usage
+#### UI Configuration
 
-```python
-cfg.objc_verbose_monitor = True
-```
-
-## UI Configuration
-
-Hilda contains minimal UI for examining the target state.
+Hilda contains a minimal UI for examining the target state.
 The UI is divided into views:
 
 - Registers
@@ -470,7 +396,31 @@ ui.colors.address = 'red'
 ui.color.title = 'green'
 ```
 
-## Symbol objects
+### Python API
+
+Hilda provides a comprehensive API wrappers to access LLDB capabilities.
+This API may be used to access process memory, trigger functions, place breakpoints and much more!
+
+Also, in addition to access this API using the [Hilda shell](#inside-a-hilda-shell), you may also use pure-python script using any of the `create_hilda_client_using_*` APIs.
+
+Consider the following snippet as an example of such usage:
+
+```python
+from hilda.launch_lldb import create_hilda_client_using_attach_by_name
+
+# attach to `sysmond`
+p = create_hilda_client_using_attach_by_name('sysmond')
+
+# allocate 10 bytes and print their address
+print(p.symbols.malloc(10))
+
+# detach
+p.detach()
+```
+
+Please note this script must be executed using `xcrun python3` in order for it to be able to access LLDB API.
+
+#### Symbol objects
 
 In Hilda, almost everything is wrapped using the `Symbol` Object. Symbol is just a nicer way for referring to addresses
 encapsulated with an object allowing to deref the memory inside, or use these addresses as functions.
@@ -577,7 +527,7 @@ p.bp('symbol_name')
 p.bp('symbol_name', module_name='ModuleName')
 ```
 
-## Globalized symbols
+#### Globalized symbols
 
 Usually you would want/need to use the symbols already mapped into the currently running process. To do so, you can
 access them using `symbols.<symbol-name>`. The `symbols` global object is of type `SymbolsJar`, which is a wrapper
@@ -622,7 +572,7 @@ jar = jar.code()
 jar.monitor(regs={'x0': 'x'}, bt=True)
 ```
 
-### Objective-C Classes
+#### Objective-C Classes
 
 The same as symbols applies to Objective-C classes name resolution. You can either:
 
@@ -675,7 +625,7 @@ dictionary = NSDictionary.capture_self(True)
 dictionary.show()
 ```
 
-## Objective-C Objects
+#### Objective-C Objects
 
 In order to work with ObjC objects, each symbol contains a property called
 `objc_symbol`. After calling, you can work better with each object:
@@ -741,7 +691,7 @@ abc_string = p.evaluate_expression('[NSString stringWithFormat:@"abc"]')
 print(abc_string.po())
 ```
 
-## Using snippets
+#### Using snippets
 
 Snippets are extensions for normal functionality used as quick cookbooks for day-to-day tasks of a debugger.
 

{hilda-2.0.2.dist-info → hilda-2.0.4.dist-info}/RECORD

@@ -3,13 +3,13 @@ gifs/ui.png,sha256=iaRwNZ9qVWUkUe2TJb_6VPsTu--7HrElA2duWiyZ-Oc,131
 gifs/xpc_print_message.gif,sha256=i5S8Y9bJm9n-NtOipFTAC8_jUR4uZCM4sOap_ccJX0k,939935
 hilda/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 hilda/__main__.py,sha256=KWRqvukK4wraxCMtvH5nO25mFXLO5aWXa7z_VfAtbO8,90
-hilda/_version.py,sha256=ld-j3TUpFlKQqUdd5gCrvB3csNXi_lXdKFr5cuIfSdk,411
-hilda/cli.py,sha256=XCL9vD4zWkK2GHnkeBXZ5AC08iC4rtHYBydgi6SzGJI,3325
+hilda/_version.py,sha256=dd-KZw8-eltAgI3rgXg7IQu4qJc9i2jbpZFwyH2XNrA,411
+hilda/cli.py,sha256=FQtOg1iFRtNdVVes_SchIoidOWAENhsLItwXBWCgWgc,3625
 hilda/common.py,sha256=VFtpOH9IRqbu6lONM6Hz-PxcdJfktgS3akJv5UCHO0s,523
-hilda/exceptions.py,sha256=a2EGckJ66ArG2LZJVnUz91gRkqQyc9AEtbS_mfZuI3s,2141
+hilda/exceptions.py,sha256=8L1OvOqns4O4ieiH4YlrMbZkk_PvuyCq4UyqFAodkF8,2042
 hilda/hilda_ascii_art.html,sha256=-9YCjAKdGbjtdd6uoKrxkkcJq7j16r4dGka2bZ27b4o,120119
-hilda/hilda_client.py,sha256=QQowZuvTu0Z9heGaBmLoKqjRa7BdjezEnkx15Jt-y7Y,43997
-hilda/launch_lldb.py,sha256=OeZjIILxt6lVQdZnD67E2QHfEK2XU_B-HTa5ZI0NTkw,7920
+hilda/hilda_client.py,sha256=-rajiYqPxLK4n19k9DbFUDGqDNHpl57gYvRuLKC4SW4,45324
+hilda/launch_lldb.py,sha256=sD-02HERIFQEYoPM9JrRfFOTjHE2QUt3L0pNgFsyAEQ,7186
 hilda/lldb_entrypoint.py,sha256=vTiClzfiTtjorlxEfIsI-W657KEGobx74qDhaZ8nPhM,1007
 hilda/lldb_importer.py,sha256=LrIQnigDG3wgmIPXya67oBlWubkDgV-rEpzfWNEYCoc,553
 hilda/objective_c_class.py,sha256=Xyw7FucNVcu8NqhB0Gy-OjaN_2DmCywn6pjUEwyd1Hk,11760
@@ -18,7 +18,7 @@ hilda/registers.py,sha256=moGS9MXrfm8vmnqDKWZSg4wmZNydGUadui9uwEwzhsI,856
 hilda/symbol.py,sha256=_TSQqFysRs82BFNGX9o_ZbkrwzSsWq3FiMbX92VKoPo,7200
 hilda/symbols_jar.py,sha256=1GPgrbXdsxiirMufrWqVi-DHF9qDXgy_HMtWJD4dJuE,6447
 hilda/ipython_extensions/events.py,sha256=uV30ZJMwpRw9YwGnQ40uAOh9Mtr8QGJFB7cZeY-pCow,1960
-hilda/ipython_extensions/keybindings.py,sha256=2NiTwfakowCj1VT6eEDvMeMiFx_pBvkhVDaQPuX69uM,957
+hilda/ipython_extensions/keybindings.py,sha256=kKArfRWyJ261ieUot4CVTGRmwbnixYtrpgiFCnBfDag,1013
 hilda/ipython_extensions/magics.py,sha256=ULb63-OyIaWwvSfwRvEG_65ibaI2RTxeX8yPJK8pbc0,1300
 hilda/objective_c/from_ns_to_json.m,sha256=5Ddl0UJLQXlDYwR_yjE4yZk1aOsJGxoy1oRnhZHPrTw,2847
 hilda/objective_c/get_objectivec_class_by_module.m,sha256=DC8S8XaWsQSOJZWVWhATr98SZQobA3MmclLsBJGZTcU,704
@@ -46,9 +46,9 @@ hilda/snippets/macho/macho_load_commands.py,sha256=OsajG2xWuRwhYhj9f-lnUiNe43Yum
 hilda/ui/colors.json,sha256=f-ITquY3IInQreviTy23JfmxfJrGM1_MivACf1GKGqM,262
 hilda/ui/ui_manager.py,sha256=BmzI1sBx0PYCQDlB9Al7wsTEAMJxaJ7NW0DS4C7g5-0,2265
 hilda/ui/views.py,sha256=1u_eZzw7wAEP1bm_-9nkqgGhMSX__woiUuoBgnsAKVM,7843
-hilda-2.0.2.dist-info/LICENSE,sha256=M-LVJ0AFAYB82eueyl8brh-QLPe-iLNVgbCi79-3TDo,1078
-hilda-2.0.2.dist-info/METADATA,sha256=agMwzWcpALitue6mJodwdAa3VHvhvfNdlOAKd3GIukk,23891
-hilda-2.0.2.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-hilda-2.0.2.dist-info/entry_points.txt,sha256=9n3O3j6V3XnVR_GcFqCWNgRAbalfukTSW2WvghsLVmA,46
-hilda-2.0.2.dist-info/top_level.txt,sha256=TVD7l1WkE1noT866YqPFhiQnjYCYZM5Xz54v_3EYpnI,11
-hilda-2.0.2.dist-info/RECORD,,
+hilda-2.0.4.dist-info/LICENSE,sha256=M-LVJ0AFAYB82eueyl8brh-QLPe-iLNVgbCi79-3TDo,1078
+hilda-2.0.4.dist-info/METADATA,sha256=8kOmj9XaEs7kmlquqZcng4mlTKQ4hUUDUk0elsyXIFQ,23306
+hilda-2.0.4.dist-info/WHEEL,sha256=mguMlWGMX-VHnMpKOjjQidIo1ssRlCFu4a4mBpz1s2M,91
+hilda-2.0.4.dist-info/entry_points.txt,sha256=9n3O3j6V3XnVR_GcFqCWNgRAbalfukTSW2WvghsLVmA,46
+hilda-2.0.4.dist-info/top_level.txt,sha256=TVD7l1WkE1noT866YqPFhiQnjYCYZM5Xz54v_3EYpnI,11
+hilda-2.0.4.dist-info/RECORD,,

{hilda-2.0.2.dist-info → hilda-2.0.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.43.0)
+Generator: setuptools (70.1.1)
 Root-Is-Purelib: true
 Tag: py3-none-any