{"id":27160324,"url":"https://github.com/metallikecuda/gpumkat","last_synced_at":"2026-04-10T19:05:01.497Z","repository":{"id":285106783,"uuid":"957091352","full_name":"MetalLikeCuda/gpumkat","owner":"MetalLikeCuda","description":"Gpumkat is a shader debugger for metal which is designed to do what instruments can't do","archived":false,"fork":false,"pushed_at":"2025-04-05T18:06:58.000Z","size":325,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T18:32:35.187Z","etag":null,"topics":["alternative","api","better","control","cuda","darwin","debugger","debugging","debugging-tool","gpu","innovative","macos","management","metal","okerew","profiler","release","shaders","threads"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MetalLikeCuda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-29T14:36:09.000Z","updated_at":"2025-04-05T18:03:33.000Z","dependencies_parsed_at":"2025-04-05T18:26:34.626Z","dependency_job_id":null,"html_url":"https://github.com/MetalLikeCuda/gpumkat","commit_stats":null,"previous_names":["metallikecuda/gpumkat"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetalLikeCuda%2Fgpumkat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetalLikeCuda%2Fgpumkat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetalLikeCuda%2Fgpumkat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MetalLikeCuda%2Fgpumkat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MetalLikeCuda","download_url":"https://codeload.github.com/MetalLikeCuda/gpumkat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247947823,"owners_count":21023058,"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":["alternative","api","better","control","cuda","darwin","debugger","debugging","debugging-tool","gpu","innovative","macos","management","metal","okerew","profiler","release","shaders","threads"],"created_at":"2025-04-08T23:41:27.426Z","updated_at":"2026-04-10T19:05:01.486Z","avatar_url":"https://github.com/MetalLikeCuda.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gpumkat\n\n\u003cimg src=\"gpumkat_icon.png\"\u003e\n\na GPU kernel analysis tool for macOS Metal with many features ranging from analyzing performance, cache hit rates, interface metrics, gpu software states, shader optimization recommendations, stack traces, recording timelines, traces and more.\n\n## Requirements:\n\n- arm MacOS and M series chip\n- any platform that supports metal\n- metal api\n- xcode\n- homebrew \n- json-c 0.18 (installed with homebrew)\n- curl \n\n## Installation\n\nTo install gpumkat run this command.\n\n```sh\ncurl -L -o gpumkat.tar.gz https://github.com/MetalLikeCuda/osxiec/releases/download/%s/gpumkat.tar.gz \u0026\u0026 tar -xvzf gpumkat.tar.gz \u0026\u0026 cd gpumkat \u0026\u0026 sudo sh install.sh\n```\n\nreplace %s with the latest version\n\n## Usage\n\n```sh\ngpumkat \u003cpath_to_config_file\u003e\n```\n\n---\n### Commands you can use\n\n**To update**\n\n```sh\ngpumkat -update\n```\n\n**To add plugins**\n\n```sh\ngpumkat -add-plugin \u003cpath_to_plugin\u003e\n```\n\n**To remove plugins**\n\n```sh\ngpumkat -remove-plugin \u003cpath_to_plugin\u003e\n```\n\n**To get help**\n\n```sh\ngpumkat -help\n```\n\n**To get version information**\n\n```sh\ngpumkat --version\n```\n\n**To run tests**\n```sh\ngpumkat -test \u003cpath_to_test_config_file\u003e\n```\n\n**To run lsp server**\n\n```sh\ngpumkat -lsp\n```\n\n## Examples\n\nMore examples can be seen in the examples folder\n\n### Example config:\n\n```json\n{\n    \"metallib_path\": \"default.metallib\",\n    \"function_name\": \"compute_shader\",\n    \"logging\": {\n        \"enabled\": true,\n        \"log_file_path\": \"gpumkat_profiler.log\",\n        \"log_level\": 3,\n        \"log_timestamps\": true\n    },\n    \"debug\": {\n        \"enabled\": true,\n        \"print_variables\": true,\n        \"step_by_step\": true,\n        \"break_before_dispatch\": true,\n        \"verbosity_level\": 2,\n        \"breakpoints\": [\n            {\n                \"condition\": \"BeforeDispatch\",\n                \"description\": \"After buffer initialization\"\n            }\n        ],\n        \"error_handling\": {\n            \"catch_warnings\": true,\n            \"catch_memory_errors\": true,\n            \"catch_shader_errors\": true,\n            \"catch_validation_errors\": true,\n            \"break_on_error\": false,\n            \"max_error_count\": 100,\n            \"min_severity\": 1\n        },\n        \"timeline\": {\n            \"enabled\": true,\n            \"output_file\": \"gpumkat_timeline2.json\",\n            \"track_buffers\": true,\n            \"track_shaders\": true,\n            \"track_performance\": true,\n            \"max_events\": 1000\n        },\n        \"low_end_gpu\": {\n            \"enabled\": true,\n            \"compute\": {\n                \"processing_units_availability\": 0.6,\n                \"clock_speed_reduction\": 0.4,\n                \"compute_unit_failures\": 2\n            },\n            \"memory\": {\n                \"bandwidth_reduction\": 0.6,\n                \"latency_multiplier\": 3.0,\n                \"available_memory\": 536870912,\n                \"memory_error_rate\": 0.02\n            },\n            \"thermal\": {\n                \"thermal_throttling_threshold\": 85.0,\n                \"power_limit\": 50.0,\n                \"enable_thermal_simulation\": true\n            },\n            \"logging\": {\n                \"detailed_logging\": true,\n                \"log_file_path\": \"low_end_gpu_simulation.log\"\n            }\n        },\n        \"async_debug\": {\n            \"enable_async_tracking\": true,\n            \"log_command_status\": true,\n            \"detect_long_running_commands\": true,\n            \"long_command_threshold\": 2.5,\n            \"generate_async_timeline\": true\n        },\n        \"thread_control\": {\n            \"enable_thread_debugging\": true,\n            \"dispatch_mode\": 3,\n            \"log_thread_execution\": true,\n            \"validate_thread_access\": true,\n            \"simulate_thread_failures\": true,\n            \"thread_failure_rate\": 0.05,\n            \"custom_thread_group_size\": [\n                32,\n                1,\n                1\n            ],\n            \"custom_grid_size\": [\n                1024,\n                1,\n                1\n            ],\n            \"thread_order_file\": \"custom_thread_order.txt\"\n        }\n    },\n    \"buffers\": [\n        {\n            \"name\": \"inputBuffer\",\n            \"size\": 1024,\n            \"type\": \"float\",\n            \"contents\": [\n                1.0,\n                2.0,\n                3.0,\n                4.0,\n                5.0\n            ]\n        },\n        {\n            \"name\": \"outputBuffer\",\n            \"size\": 1024,\n            \"type\": \"float\",\n            \"contents\": []\n        }\n    ],\n    \"image_buffers\": [\n        {\n            \"name\": \"inputImage\",\n            \"image_path\": \"/path/to/image.png\",\n            \"width\": 0,\n            \"height\": 0,\n            \"type\": \"float\"\n        }\n    ]\n}\n```\n\n### Example kernel:\n\n```c\n#include \u003cmetal_stdlib\u003e\nusing namespace metal;\n\nkernel void compute_shader(const device float *input [[buffer(0)]],\n                           device float *output [[buffer(1)]],\n                           uint index [[thread_position_in_grid]]) {\n    output[index] = input[index] * 2.0;\n}\n```\n\n### Example Logs:\n\u003cimg src=\"gpumkat_logs.png\"\u003e\n\n## Building\n\nYou can build gpumkat using cmake with the following command:\n```sh\nmkdir build \u0026\u0026 cd build \u0026\u0026 cmake -S .. -B . -G \"Ninja\" \u0026\u0026 ninja\n```\n\n### Notes:\n\nOther shaders you can use are located in the list of shaders: https://github.com/MetalLikeCuda/list_of_metal_shaders.md\n\nSome things like temperature are approximated so it's better to just use instruments if you want very low level hardware specific data, though for normal debugging this should be better.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetallikecuda%2Fgpumkat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetallikecuda%2Fgpumkat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetallikecuda%2Fgpumkat/lists"}