{"id":18909308,"url":"https://github.com/mono/sdb","last_synced_at":"2025-04-15T06:30:33.413Z","repository":{"id":11797929,"uuid":"14342932","full_name":"mono/sdb","owner":"mono","description":"A command line client for the Mono soft debugger.","archived":true,"fork":false,"pushed_at":"2021-09-02T09:48:25.000Z","size":304,"stargazers_count":117,"open_issues_count":17,"forks_count":37,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-03-22T01:19:49.910Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.mono-project.com","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mono.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-11-12T19:37:13.000Z","updated_at":"2024-11-17T15:58:44.000Z","dependencies_parsed_at":"2022-09-23T02:11:55.690Z","dependency_job_id":null,"html_url":"https://github.com/mono/sdb","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mono%2Fsdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mono%2Fsdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mono%2Fsdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mono%2Fsdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mono","download_url":"https://codeload.github.com/mono/sdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249020582,"owners_count":21199582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T09:32:42.145Z","updated_at":"2025-04-15T06:30:32.210Z","avatar_url":"https://github.com/mono.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SDB: Mono Soft Debugger Client\n\nSDB is a command line client for Mono's soft debugger, a cooperative debugger\nthat is part of the Mono VM. It tries to be similar in command syntax to tools\nsuch as GDB and LLDB.\n\n## Building\n\nBuilding and using SDB requires a basic POSIX-like environment, a Bash-like\nshell, the `libedit` library (or an API/ABI-compatible replacement), and an\ninstalled Mono framework.\n\nFirst, clone the submodules:\n\n    $ git submodule update --init --recursive\n\nTo build, run:\n\n    $ make\n\nIf the build succeeds, you can install SDB with:\n\n    $ make install\n\n(You may need to invoke it with `sudo` or some such command.)\n\nYou can also run SDB from within the build directory by appending it to `PATH`\nand invoking `sdb-dev`. This is mainly intended for development of SDB itself.\nAn example:\n\n    $ export PATH=`pwd`/bin:$PATH\n    $ sdb-dev\n    Welcome to the Mono soft debugger (sdb 1.0.5058.39468)\n    Type 'help' for a list of commands or 'quit' to exit\n\n    (sdb)\n\nYou can run the SDB test suite with:\n\n    $ make check\n\n(This requires an F# installation.)\n\nThe following variables can be set in your environment or on the `make` command\nline to affect the build:\n\n* `CAT`: Path to the `cat` POSIX utility.\n* `CD`: Path to the `cd` POSIX utility.\n* `CHMOD`: Path to the `chmod` POSIX utility.\n* `CP`: Path to the `cp` POSIX utility.\n* `ECHO`: Path to the `echo` POSIX utility.\n* `FSHARPC`: Which F# compiler executable to use.\n* `FSHARPC_FLAGS`: Flags to pass to the F# compiler.\n* `FSHARPC_TEST_FLAGS`: Flags to pass to the F# compiler for tests.\n* `GENDARME`: Which Gendarme executable to use (optional).\n* `GENDARME_FLAGS`: Flags to pass to Gendarme.\n* `INSTALL`: Path to the `install` POSIX utility.\n* `MCS`: Which C# compiler executable to use.\n* `MCS_FLAGS`: Flags to pass to the C# compiler.\n* `MCS_TEST_FLAGS`: Flags to pass to the C# compiler for tests.\n* `MKDIR`: Path to the `mkdir` POSIX utility.\n* `NUGET`: Which NuGet executable to use.\n* `PKG_CONFIG`: Path to the `pkg-config` utility.\n* `RM`: Path to the `rm` POSIX utility.\n* `SED`: Path to the `sed` POSIX utility.\n* `TAR`: Path to the `tar` POSIX utility.\n* `MSBUILD`: Which MSBuild executable to use.\n* `MSBUILD_FLAGS`: Flags to pass to MSBuild.\n\nAdditionally, `MODE` can be set to `Debug` (default) or `Release` to indicate\nthe kind of build desired. `PREFIX` can be set to specify the path that the\n`install` and `uninstall` targets should operate within (defaults to\n`/usr/local`).\n\nFinally, `MONO_PREFIX` and `MONO_BINARY` can be set to tell the `check` target\nwhich Mono executable should be used. See the description of `RuntimePrefix`\nand `RuntimeExecutable` further down for more information.\n\n## Usage\n\nRunning a program is simple:\n\n    $ cat test.cs\n    using System;\n    using System.Diagnostics;\n\n    static class Program\n    {\n        static void Main()\n        {\n            var str = \"Foo!\";\n\n            Foo(str);\n        }\n\n        static void Foo(string str)\n        {\n            Console.WriteLine(str);\n\n            Bar();\n        }\n\n        static void Bar()\n        {\n            Debugger.Break();\n        }\n    }\n    $ mcs -debug test.cs\n    $ sdb\n    Welcome to the Mono soft debugger (sdb 1.0.5060.15368)\n    Type 'help' for a list of commands or 'quit' to exit\n\n    (sdb) r test.exe\n    Inferior process '5234' ('test.exe') started\n    Foo!\n    Inferior process '5234' ('test.exe') suspended\n    #0 [0x00000001] Program.Bar at /home/alexrp/Projects/tests/cs/test.cs:22\n            Debugger.Break();\n\nA stack trace can be generated with `bt`:\n\n    (sdb) bt\n    #0 [0x00000001] Program.Bar at /home/alexrp/Projects/tests/cs/test.cs:22\n            Debugger.Break();\n    #1 [0x00000007] Program.Foo at /home/alexrp/Projects/tests/cs/test.cs:17\n            Bar();\n    #2 [0x00000008] Program.Main at /home/alexrp/Projects/tests/cs/test.cs:10\n            Foo(str);\n\nWe can select a frame and inspect locals:\n\n    (sdb) f up\n    #1 [0x00000007] Program.Foo at /home/alexrp/Projects/tests/cs/test.cs:17\n            Bar();\n    (sdb) p str\n    string it = \"Foo!\"\n\nOr globals:\n\n    (sdb) p Environment.CommandLine\n    string it = \"/home/alexrp/Projects/tests/cs/test.exe\"\n\nTo continue execution, do:\n\n    (sdb) c\n    Inferior process '5234' ('test.exe') resumed\n    Inferior process '5234' ('test.exe') exited\n    (sdb)\n\nWe can then exit SDB:\n\n    (sdb) q\n    Bye\n\nFor more commands, consult `help` in SDB.\n\n## Options\n\nSDB has a few command line options that are useful for automation. For the full\nlist, issue `sdb --help`.\n\nFirst of all, all non-option arguments passed to SDB are treated as commands\nthat SDB will execute at startup. For instance:\n\n    $ sdb \"run test.exe\"\n\nOr:\n\n    $ sdb \"args --foo --bar baz\" \"run test.exe\"\n\nThis starts SDB and immediately executes `test.exe` with the given arguments.\n\nThe first option is `-f`. This option specifies files that SDB should read\ncommands from. These commands are executed before any commands specified as\nnon-option arguments. This option is useful for longer command sequences that\nare easier to maintain in a separate file. Example:\n\n    $ cat cmds.txt\n    args --foo --bar baz\n    run test.exe\n    $ sdb -f cmds.txt\n\nThe second option is `-b`. This runs SDB in batch mode; that is, it will exit\nas soon as all commands have finished and no inferior process is running. This\ngoes well with `-f` for running programs regularly under SDB.\n\n## Settings\n\nOne configuration element that you almost certainly need to alter is the\n`RuntimePrefix` string value. It is set to `/usr` by default, regardless of\nOS, which is probably not desirable everywhere. For example, on Windows, you\nwill want to set it to something like `C:\\Program Files (x86)\\Mono-3.0.10`.\nOr if you have Mono in some other directory, you might set it to e.g.\n`/opt/mono`.\n\nThe `RuntimeExecutable` element is another way to specify which Mono executable\nto use. If `RuntimePrefix` is empty, then `RuntimeExecutable` is taken as the\nfull path to the Mono executable. If both elements are non-empty, they are\ncombined as `Path.Combine(RuntimePrefix, \"bin\", RuntimeExecutable)`. This\nconfiguration element is useful for switching between `mono32` and `mono64` on\nOS X in particular.\n\nYou may want to set `DisableColors` to `true` if you don't want the fancy ANSI\ncolor codes that SDB emits.\n\nFinally, three useful settings for debugging SDB itself exist: `DebugLogging`\ncan be set to `true` to make SDB spew a bunch of diagnostic information.\n`LogInternalErrors` can be set to `true` to log any internal errors that are\nencountered in the Mono debugging libraries. `LogRuntimeSpew` can be set to\n`true` to log all messages from the Mono VM.\n\n## Paths\n\nWhen configuration elements are changed with `config set`, SDB will store the\nconfiguration data in `~/.sdb.cfg`. The content of the file is the .NET binary\nserialization of the `Mono.Debugger.Client.Configuration` class. This file is\nread on startup if it exists.\n\nAt startup, SDB will scan the `~/.sdb` directory for plugin assemblies. It will\nattempt to load all command definitions.\n\nFinally, SDB will read `~/.sdb.rc` and execute any commands (one per line) from\nit. This is useful if you prefer to change your settings with commands that you\nwrite down manually, rather than storing the data in a binary file.\n\n## Environment\n\nThe `SDB_COLORS` variable can be set to `disable` to tell SDB to not use colors\nin output. Normally, SDB will not use colors if it detects that `stdout` has\nbeen redirected, that `TERM` is set to `dumb` (or not set at all), or if the\n`DisableColors` configuration element is `true`.\n\n`SDB_CFG` can be set to a specific configuration file to use instead of the\ndefault `~/.sdb.cfg`. If set to the empty string (i.e. `SDB_CFG=\"\" sdb`), SDB\nwill not load any configuration file at all, and changed configuration values\nwill not be saved.\n\nThe `SDB_PATH` variable can be set to a list of additional directories that SDB\nwill scan for plugin assemblies in. Each directory should be separated by a\nsemicolon (Windows) or a colon (POSIX).\n\n`SDB_DEBUG` can be set to `enable` to make SDB print diagnostic information\nwhile debugging. This may be useful to debug SDB itself.\n\n## Plugins\n\nAt the moment, SDB has one extension point which is the\n`Mono.Debugger.Client.Command` class and the related\n`Mono.Debugger.Client.CommandAttribute` class. A class implementing `Command`\nthat is tagged with `CommandAttribute` will be instantiated at startup time and\nput into the root command list.\n\nFor SDB to find custom commands, they should be compiled into `.dll` assemblies\nand put in `~/.sdb` (or some other directory specified in `SDB_PATH`). Plugin\nassemblies can also be loaded manually with the `plugin` command.\n\nHere's an example of compiling and using a test plugin:\n\n    $ cat test.cs\n    using Mono.Debugger.Client;\n\n    [Command]\n    public sealed class MyCommand : Command\n    {\n        public override string[] Names\n        {\n            get { return new[] { \"mycmd\" }; }\n        }\n\n        public override string Summary\n        {\n            get { return \"Performs magic.\"; }\n        }\n\n        public override string Syntax\n        {\n            get { return \"mycmd\"; }\n        }\n\n        public override string Help\n        {\n            get { return \"Some sort of detailed help text goes here.\"; }\n        }\n\n        public override void Process(string args)\n        {\n            Log.Info(\"Hello! I received: {0}\", args);\n        }\n    }\n    $ mcs -debug -t:library test.cs -r:$(dirname $(which sdb))/../lib/sdb/sdb.exe -out:$HOME/.sdb/test.dll\n    $ sdb\n    Welcome to the Mono soft debugger (sdb 1.0.5061.14716)\n    Type 'help' for a list of commands or 'quit' to exit\n\n    (sdb) h mycmd\n\n      mycmd\n\n    Some sort of detailed help text goes here.\n\n    (sdb) mycmd foo bar baz\n    Hello! I received: foo bar baz\n\nYou can look at SDB's own command classes for some examples of things that you\ncan do in your commands.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmono%2Fsdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmono%2Fsdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmono%2Fsdb/lists"}