{"id":21379390,"url":"https://github.com/tgstation/rust-g","last_synced_at":"2026-01-06T10:13:48.078Z","repository":{"id":38011523,"uuid":"127494547","full_name":"tgstation/rust-g","owner":"tgstation","description":"Rust based libraries for tgstation ","archived":false,"fork":false,"pushed_at":"2024-04-21T07:21:33.000Z","size":1756,"stargazers_count":24,"open_issues_count":12,"forks_count":96,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-05-02T05:16:20.871Z","etag":null,"topics":["byond","libaries","rust","ss13","tgstation13"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/tgstation.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":"2018-03-31T03:12:57.000Z","updated_at":"2024-05-30T03:48:10.181Z","dependencies_parsed_at":"2023-01-31T06:01:45.935Z","dependency_job_id":"8c06f859-c085-4d97-bccf-93191e72ecec","html_url":"https://github.com/tgstation/rust-g","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgstation%2Frust-g","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgstation%2Frust-g/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgstation%2Frust-g/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgstation%2Frust-g/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tgstation","download_url":"https://codeload.github.com/tgstation/rust-g/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225878756,"owners_count":17538504,"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":["byond","libaries","rust","ss13","tgstation13"],"created_at":"2024-11-22T10:19:32.215Z","updated_at":"2026-01-06T10:13:48.072Z","avatar_url":"https://github.com/tgstation.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rust-g\n\nrust-g (pronounced rusty-g) is a library which offloads certain expensive or\ndifficult tasks from BYOND.\n\nThis library is currently used in the [/tg/station] codebase, and is required for\nit to run. A pre-compiled DLL version can be found in the repo root of codebases that use it,\nbut you can build your own from this repo (and you should if you're running a server).\n\nBuilds can also be found on the [releases page] **but should only be used for Windows**,\nas Linux has compatibility issues across distributions.\n\n[releases page]: https://github.com/tgstation/rust-g/releases\n\n## Dependencies\n\nThe [Rust] compiler:\n\n1. Install the Rust compiler's dependencies (primarily the system linker):\n\n   * Ubuntu: `sudo apt-get install gcc-multilib`\n   * Windows (MSVC): [Build Tools for Visual Studio 2017][msvc]\n   * Windows (GNU): No action required\n\n1. Use [the Rust installer](https://rustup.rs/), or another Rust installation method,\n   or run the following:\n\n    ```sh\n    curl https://sh.rustup.rs -sSfo rustup-init.sh\n    chmod +x rustup-init.sh\n    ./rustup-init.sh\n    ```\n\n1. Set the default compiler to **32-bit**:\n\n    ```sh\n    # Clone the `rust-g` repository to a directory of your choice\n    git clone https://github.com/tgstation/rust-g.git\n    # in the `rust-g` directory...\n    cd rust-g\n    # Linux\n    rustup target add i686-unknown-linux-gnu\n    # Windows\n    rustup target add i686-pc-windows-msvc\n    ```\n\nSystem libraries:\n\n* Ubuntu and Debian users run:\n\n    ```sh\n    sudo dpkg --add-architecture i386\n    sudo apt-get update\n    sudo apt-get install zlib1g-dev:i386\n    ```\n\n* Other Linux distributions install the appropriate **32-bit development** and **32-bit runtime** packages.\n\nIf you want to use the `pc-windows-gnu` or similar other target ABI, do the following:\n1. Change the `\"rust-analyzer.cargo.target\"` setting in `.cargo/config` to `i686-pc-windows-gnu`.\n2. Run `git update-index --assume-unchanged .cargo/config`, which will tell git to 'ignore' the changes you made.\n3. If you find yourself ever wanting to change back, run `git update-index --no-assume-unchanged .cargo/config`.\n\n## Compiling\n\nThe [Cargo] tool handles compilation, as well as automatically downloading and\ncompiling all Rust dependencies. The default configuration is suitable for\nuse with the [/tg/station] codebase. To compile in release mode (recommended for\nspeed):\n\nLinux:\n```sh\nexport PKG_CONFIG_ALLOW_CROSS=1\ncargo build --release --target i686-unknown-linux-gnu\n# output: target/i686-unknown-linux-gnu/release/librust_g.so\n```\n\nWindows:\n\nIf you are using Visual Studio Code, you may use the `CONTROL + SHIFT + B` hotkey and run the `rust: cargo build (win32)` task.\n\nAlternatively:\n```sh\ncargo build --release --target i686-pc-windows-msvc\n# output: target/i686-pc-windows-msvc/release/rust_g.dll\n```\n\nIf you aren't sharing the binary with other people, consider compiling [targeting your native cpu](https://rust-lang.github.io/packed_simd/perf-guide/target-feature/rustflags.html#target-cpu) for potential performance improvements. You can do this by setting the `RUSTFLAGS` environment variable to `-C target-cpu=native`. For example, in Powershell you would use `$Env:RUSTFLAGS=\"-C target-cpu=native\"`.\n\nTo get additional features, pass a list to `--features`, for example `--features hash,url`. To get all features, pass `--features all`. To disable the default features, pass `--no-default-features`.\nYou can't use `--all-features` because of conflicting `native_tls` and `rustls_tls` features to select the mysql backend.\n\nThe default features are:\n* acreplace: Aho-Corasick string matching and replacement.\n* cellularnoise: Function to generate cellular automata-based noise.\n* dmi: DMI manipulations which are impossible or degraded from within BYOND.\n  Mostly used by the asset cache subsystem to improve load times.\n* file: Faster replacements for `file2text` and `text2file`, as well as reading or checking if files exist.\n* git: Functions for robustly checking the current git revision.\n* hash: Faster replacement for `md5`, support for SHA-1, SHA-256, and SHA-512.\n* http: Asynchronous HTTP(s) client supporting most standard methods.\n* iconforge: A much faster replacement for various bulk DM /icon operations such as [/tg/station]'s asset subsystem spritesheet generation and GAGS bundle generation.\n* json: Function to check JSON validity.\n* log: Faster log output.\n* noise: 2d Perlin noise.\n* pathfinder: An a* pathfinder used for finding the shortest path in a static node map. Not to be used for a non-static map.\n* sound_len: A mostly codec-agnostic library for reading the duration of an audio file.\n* sql: Asynchronous MySQL/MariaDB client library.\n  * There are also two sub-features: `native_tls` and `rustls_tls`. `rustls_tls` is a default feature, while the former is not.\n* time: High-accuracy time measuring.\n* toml: TOML parser.\n* url: Faster replacements for `url_encode` and `url_decode`.\n\nAdditional features are:\n* allow_non_32bit: Disables the forced compile errors on non-32bit targets. Only use this if you know exactly what you are doing.\n* batchnoise: Discrete Batched Perlin-like Noise, fast and multi-threaded - sent over once instead of having to query for every tile.\n* dice: Advanced replacement for `roll`, supporting expressive xdy dice notation.\n* poissonnoise: A way to generate a 2D poisson disk distribution ('blue noise'), which is relatively uniform.\n* redis_pubsub: Library for sending and receiving messages through Redis.\n* redis_reliablequeue: Library for using a reliable queue pattern through Redis.\n* unzip: Function to download a .zip from a URL and unzip it to a directory.\n* worleynoise: Function that generates a type of nice looking cellular noise, more expensive than cellularnoise.\n\nRegarding rust-analyzer: If you are using a feature set other than the default, you will need to adjust `rust-analyzer.cargo.features`.\n\n## Installing\n\nThe rust-g binary (`rust_g.dll` or `librust_g.so`) should be placed in the root\nof your repository next to your `.dmb`. There are alternative installation\nlocations, but this one is best supported.\n\nCompiling will also create the file `target/rust_g.dm` which contains the DM API\nof the enabled modules. To use rust-g, copy-paste this file into your project.\n\n`rust_g.dm` can be configured by creating a `rust_g.config.dm`. See the comments\nat the top of `rust_g.dm` for details.\n\n## Troubleshooting\n\nYou must build a 32-bit version of the library for it to be compatible with\nBYOND. Attempting to build a 64-bit version will fail with an explanatory error.\n\n### Linux\n\nOn Linux systems `ldd` can be used to check that the relevant runtime libraries\nare installed, without which BYOND will fail to load rust-g. The following is\nsample output, but the most important thing is that nothing is listed as\n\"missing\".\n\n```sh\n$ ldd librust_g.so  # Linux\n    linux-gate.so.1 (0xf7f8b000)\n    libgcc_s.so.1 =\u003e /lib/i386-linux-gnu/libgcc_s.so.1 (0xf7957000)\n    libpthread.so.0 =\u003e /lib/i386-linux-gnu/libpthread.so.0 (0xf7935000)\n    libm.so.6 =\u003e /lib/i386-linux-gnu/libm.so.6 (0xf7831000)\n    libdl.so.2 =\u003e /lib/i386-linux-gnu/libdl.so.2 (0xf782b000)\n    libc.so.6 =\u003e /lib/i386-linux-gnu/libc.so.6 (0xf7643000)\n    /lib/ld-linux.so.2 (0xf7f8d000)\n```\n\nIf BYOND cannot find the shared library, ensure that the directory containing\nit is included in the `LD_LIBRARY_PATH` environment variable, or tweak the search\nlogic in `rust_g.dm`:\n\n```sh\n$ export LD_LIBRARY_PATH=/path/to/tgstation\n```\n\nTo examine what locations BYOND is searching for the shared library, use\n`strace`:\n\n```sh\n$ strace DreamDaemon tgstation.dmb 45000 -trusted -logself 2\u003e\u00261 | grep 'rust_g'\n# Early in output, the file will be listed when BYOND examines every file it can see:\nopen(\"rust_g\", O_RDONLY|O_NONBLOCK|O_LARGEFILE|O_DIRECTORY|O_CLOEXEC) = -1 ENOTDIR (Not a directory)\n# BYOND will then search some common directories...\nstat64(\"/home/game/.byond/bin/rust_g\", 0xffef1110) = -1 ENOENT (No such file or directory)\nstat64(\"/home/game/.byond/bin/rust_g\", 0xffef1190) = -1 ENOENT (No such file or directory)\n# Then anywhere in LD_LIBRARY_PATH...\nopen(\"/home/game/work/ss13/byond/bin/rust_g\", O_RDONLY|O_CLOEXEC) = -1 ENOENT (No such file or directory)\n# Then in several interesting places where ld-linux looks...\nopen(\"tls/i686/sse2/cmov/rust_g\", O_RDONLY|O_CLOEXEC) = -1 ENOENT (No such file or directory)\n    ... snip ...\nopen(\"cmov/rust_g\", O_RDONLY|O_CLOEXEC) = -1 ENOENT (No such file or directory)\n# Until finding the library fails or succeeds (a value other than -1 indicates success):\nopen(\"rust_g\", O_RDONLY|O_CLOEXEC)      = 4\n# After that it goes back to the scanning from startup.\nopen(\"rust_g\", O_RDONLY|O_NONBLOCK|O_LARGEFILE|O_DIRECTORY|O_CLOEXEC) = -1 ENOTDIR (Not a directory)\n```\n\n---\n\nIf you're still having problems, ask in the [Coderbus Discord]'s\n`#tooling-questions` channel.\n\n[/tg/station]: https://github.com/tgstation/tgstation\n[Rust]: https://rust-lang.org\n[Cargo]: https://doc.rust-lang.org/cargo/\n[rustup]: https://rustup.rs/\n[msvc]: https://visualstudio.microsoft.com/visual-cpp-build-tools/\n[Coderbus Discord]: https://discord.gg/Vh8TJp9\n\n## License\n\nThis project is licensed under the [MIT license](https://en.wikipedia.org/wiki/MIT_License).\n\nSee [LICENSE](./LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgstation%2Frust-g","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftgstation%2Frust-g","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgstation%2Frust-g/lists"}