{"id":17442564,"url":"https://github.com/jez/symbol","last_synced_at":"2025-12-12T13:30:14.033Z","repository":{"id":73798703,"uuid":"149717657","full_name":"jez/symbol","owner":"jez","description":"🔨 A build tool for Standard ML","archived":false,"fork":false,"pushed_at":"2019-06-05T00:34:29.000Z","size":79,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-08T18:17:34.187Z","etag":null,"topics":["cli","sml"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-09-21T06:07:04.000Z","updated_at":"2022-01-14T19:01:06.000Z","dependencies_parsed_at":"2023-03-25T11:17:48.693Z","dependency_job_id":null,"html_url":"https://github.com/jez/symbol","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/jez%2Fsymbol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jez%2Fsymbol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jez%2Fsymbol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jez%2Fsymbol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jez","download_url":"https://codeload.github.com/jez/symbol/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239679610,"owners_count":19679500,"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":["cli","sml"],"created_at":"2024-10-17T16:17:49.773Z","updated_at":"2025-12-12T13:30:13.987Z","avatar_url":"https://github.com/jez.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Symbol\n\n[![Build Status](https://travis-ci.org/jez/symbol.svg?branch=master)](https://travis-ci.org/jez/symbol)\n\n\u003e A build tool for Standard ML\n\nSymbol is a build tool for Standard ML. It's designed to work alongside and on\ntop of existing SML build tools, like SML/NJ's CM and MLton's MLBasis files.\n\nHere's a quick screencast to show off its features:\n\n[![A quick demo of Symbol](https://asciinema.org/a/JjPtmatmrkmPhbkkNF1XHDKM4.svg)](https://asciinema.org/a/JjPtmatmrkmPhbkkNF1XHDKM4)\n\n\u003c!-- TODO(jez) set up https://symbol.sh --\u003e\n\n- - -\n\nSymbol's key features are:\n\n- **Designed to build executables**\n\n  Symbol builds and installs runnable executables for your project. With SML/NJ,\n  these executables use heap images under the hood, while MLton generates linked\n  binaries. These details are internal; the end result is always an executable\n  that you can invoke from the command line.\n\n- **Low friction for collaborators**\n\n  Symbol's executable is designed to be checked into your project's version\n  control. This means your collaborators do not have to install Symbol globally\n  before they can build your project.\n\n- **Built on `make`**\n\n  As much as possible, Symbol uses `make` to cache previous build steps. Running\n  `symbol make` a second time should usually be instant. All intermediate\n  outputs are stored into a `.symbol-work` folder in your current directory, and\n  it's always safe to delete this folder.\n\n- **Scaffold new projects**\n\n  The `symbol new` command is how you initialize new Standard ML projects. It\n  prepopulates CM and MLBasis files and copies the Symbol scripts into your\n  project, so you can jump write into your project.\n\n- **Convention over configuration**\n\n  Symbol infers information about your project from its structure. This means\n  that Symbol does not come with yet another file format to configure your\n  project; just keep using `*.cm` files for SML/NJ and `*.mlb` files for MLton.\n\n## Install\n\nInstalling Symbol globally is **only required** by the collaborators who\ninitially set up new SML projects. The global command is called `symbol-new` and\nis used solely for scaffolding new projects. Once a Symbol project has been\ncreated, a script called `symbol` will exist locally within that project.\n\n### macOS\n\nOn macOS, you can use Homebrew:\n\n```bash\nbrew install jez/formulae/symbol-new\n```\n\n### From source\n\nYou can also install from source:\n\n```bash\ngit clone https://github.com/jez/symbol\ncd symbol\nmake install\n```\n\nThis will install to `~/.local/bin/symbol-new`. If you'd like to install to\na different prefix, you can pass that to the `make` command. For example,\n\n```bash\nmake install prefix=/usr/local\n```\n\nwill instead install to `/usr/local/bin/symbol-new`.\n\n\n## Quickstart\n\n### Creating a new project\n\n```bash\n# Given `\u003ctarget\u003e` is the name to call the executable for your project:\nsymbol-new \u003ctarget\u003e\n\n# or, to create a new project with minimal scaffolding:\nsymbol-new \u003ctarget\u003e --empty\n\n# ^ This also works to initialize an existing project.\n```\n\n### Builing a Symbol project\n\n```bash\n# Build the project (by default uses SML/NJ)\n./symbol make\n\n# Build the project with MLton (takes longer, but much faster executable)\n./symbol make with=mlton\n\n# Build the project (by default uses MLton), then install to ~/.local/bin\n./symbol install\n\n# same as above, but installs to /usr/local/bin\n./symbol install prefix=/usr/local\n```\n\n### Help\n\n```bash\n# Global\nsymbol-new --help\n\n# Local\n./symbol --help\n```\n\n\n## Tips\n\nThese are some general tips for working with Symbol and Standard ML.\n\n### Project Structure\n\nSymbol adds an initial project structure with a `src/` folder. Feel free to\narrange the SML source files however you want, and pull in whatever dependencies\nyou want. **However**:\n\n- There must always be either a `\u003ctarget\u003e.cm` or `\u003ctarget\u003e.mlb` in the same\n  folder as the `symbol` script.\n\n- The `\u003ctarget\u003e.cm` must make available a `Main.main` function.\n  - This function is given directly to the `ml-build` command.\n  - See the [CM User Guide] for more information.\n\n- The choice for `\u003ctarget\u003e` cannot easily be changed after running `symbol-new`.\n  - If you do want to change it, you'll have to manually edit the `target`\n    variables in `./symbol` and `./.symbol.mk`\n\nAnd then a suggestion: keep your `\u003ctarget\u003e.cm` and `\u003ctarget\u003e.mlb` files very\ntransparent. Don't try to hide intermediate signatures, structures, or functors.\nThis will make it easier to test your code.\n\nIf you intend your project to produce **both** an executable and a library, have\na separate CM file that hides internal implementation details from downstream\nusers of your library, and keep the one that exposes everything.\n\n[CM User Guide]: https://www.smlnj.org/doc/CM/new.pdf\n\n### Your PATH\n\nThere are a few folders you might want to add or make sure are in your PATH. To\nadd all of the below folders to your PATH, add these lines to your bashrc or\nzshrc:\n\n```bash\nexport PATH=\"$PATH:.symbol-work/bin\"\nexport PATH=\"$PATH:.\"\nexport PATH=\"$PATH:$HOME/.local/bin\"\n```\n\nThe folders themselves are:\n\n-   `.symbol-work/bin`\n\n    If this folder is in your PATH, you can replace\n\n    ```\n    ❯ .symbol-work/bin/my-target\n    ```\n\n    with just\n\n    ```\n    ❯ my-target\n    ```\n\n-   `.` (the current directory)\n\n    If this folder is in your PATH, you can replace\n\n    ```\n    ❯ ./symbol make\n    ```\n\n    with just\n\n    ```\n    ❯ symbol make\n    ```\n\n-   `$HOME/.local/bin`\n\n    This is the place where `./symbol install` puts executables by default.\n    If this folder is *not* in your PATH, you can use `prefix=...` to specify a\n    folder that is on your PATH. For example:\n\n    ```\n    ./symbol install prefix=/usr/local\n    ```\n\n\n## Contributing\n\nTo learn about historical context and implementation decisions:\n\n- Read [DECISIONS.md](DECISIONS.md)\n\nTo set up your development environment:\n\n```bash\n# macOS:\nbrew bundle\n\n# linux: install the packages listed in ./Brewfile\n```\n\nFor developing on Symbol locally:\n\n```bash\n# To run the lint checks:\nmake lint\n\n# To run the tests:\nmake test\n\n# To re-record the snapshot tests:\nmake test update=1\n```\n\nTo make a new test:\n\n- Add a `.sh` file anywhere in `tests/`.\n- Make it executable.\n\nTo make a new snapshot test:\n\n- Make a new test, say `tests/foo.sh`\n- Make an empty file like `tests/foo.sh.exp`\n- Run `make test update=1`\n\nTo bump the version:\n\n- Update the VERSION in `symbol-new`\n- Update the version test output (`version.sh.exp`)\n- Commit the change, and create a new git tag with that version\n- Make a new release on GitHub (`hub release`)\n- Update the Homebrew formula\n\n\n## License\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://jez.io/MIT-LICENSE.txt)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjez%2Fsymbol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjez%2Fsymbol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjez%2Fsymbol/lists"}