{"id":13838997,"url":"https://github.com/MiguelVis/samarux","last_synced_at":"2025-07-11T00:31:56.834Z","repository":{"id":65568880,"uuid":"245517773","full_name":"MiguelVis/samarux","owner":"MiguelVis","description":"Unix-like shell for the CP/M operating system \u0026 the Z80 CPU.","archived":false,"fork":false,"pushed_at":"2023-12-30T14:10:00.000Z","size":417,"stargazers_count":38,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-17T09:12:26.082Z","etag":null,"topics":["cp-m","cpm","shell","unix-like","unix-shell","z80"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MiguelVis.png","metadata":{"files":{"readme":"README.md","changelog":"history.txt","contributing":null,"funding":null,"license":"copying.txt","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":"2020-03-06T21:13:43.000Z","updated_at":"2024-05-13T21:49:45.000Z","dependencies_parsed_at":"2024-10-22T22:04:44.063Z","dependency_job_id":null,"html_url":"https://github.com/MiguelVis/samarux","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MiguelVis%2Fsamarux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MiguelVis%2Fsamarux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MiguelVis%2Fsamarux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MiguelVis%2Fsamarux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MiguelVis","download_url":"https://codeload.github.com/MiguelVis/samarux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225669686,"owners_count":17505363,"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":["cp-m","cpm","shell","unix-like","unix-shell","z80"],"created_at":"2024-08-04T16:00:44.136Z","updated_at":"2024-11-21T03:30:25.205Z","avatar_url":"https://github.com/MiguelVis.png","language":"C","funding_links":[],"categories":["Software"],"sub_categories":["Libraries and Utilities"],"readme":"# SamaruX\n\n## Overview\n\nSamaruX is a Unix-like shell for the CP/M operating system \u0026 the Z80 CPU.\n\nIt has been developed with MESCC, my Small-C compiler version for CP/M and Z80.\n\nInstead of write separate commands for each task as in real Unix, the shell has some built-in commands.\n\nOf course, it's not at all a new idea (see [BusyBox](http://www.busybox.net) for example), but I believe this scheme has a lot of advantages in a small environment like CP/M.\n\nFor example, we can save some bytes on disk by joining some commands in one file, instead of writing them as separated ones, because we don't have to repeat some shared code in each of them.\n\nAnyway, the last versions of SamaruX support the development of external commands too.\n\nObviously, SamaruX doesn't have all functionalities of Unix, but it has some nice and useful commands, to work in a Unix-like system, under our beloved CP/M operating system.\n\nSome SamaruX functionalities are:\n- Redirection of stdin and stdout with `\u003e`, `\u003c` and `\u003e\u003e`.\n- Piping with |.\n- Environment with variables `$TERM`, `$USER`, etc.\n- Names for directories.\n- Command line history.\n- Profiling for environment customization.\n- Command aliasing.\n- Batch processing with flow control and arguments passing.\n- Complete on-line manual.\n- Prompt customization.\n- Commands: `cp`, `rm`, `mv`, `man`, `cat`, `more`, `grep`, `cd` ...\n\nThis document is not an exhaustive reference of SamaruX, but only an overview, in order to show some of its capabilities.\n\nPlease, refer to the manual for a complete description.\n\n## Builds\n\nSamaruX comes as two flawors:\n- `SX.COM` binary.\n- `SX2.COM` binary.\n\n### SX\n\nThis build configuration has almost every command as external. So it\nsupports external commands. Its main goal is to reduce the TPA\nneeded to run SamaruX. But it needs more disk space.\n\n### SX2\n\nThis build configuration has every command as built-in. It does not\nsupport external commands. Its main goal is to reduce the disk space\nneeded to run SamaruX. But it needs a bigger TPA.\n\n## Named directories\n\nSamaruX has support for named directories.\n\nWith the use of `diralias`, you can reference a directory (a drive and user specification) with a name. IE:\n\n```\ndiralias system a0:\ndiralias temp m0:\ndiralias mescc a3:\n\ncat mescc:sx.c | more\nls system:*.x\ncd temp:\n```\n\nIt's a good idea to include the diralias commands in the SamaruX profile.\n\n## Executing SamaruX external commands\n\nSamaruX will search the external command files in the directory specified in the environment variable `BINDIR`:\n\n```\nenv BINDIR system:\n```\n\nIt this variable does not exists, or it's not valid, SamaruX will search the external command files in the current working directory.\n\nIf you prefix the filename with a directory, Samarux will search the external command file there:\n\n```\nmescc:cc myprog\n```\n\nYou can force SamaruX to search a external command file in the current working directory, if you prefix the filename with the character `:`, as in:\n\n```\n:cc\n```\n\n## Searching manuals with the command `man`\n\nSamaruX will seach the manual files in the directory specified in the environment variable `MANPATH`:\n\n```\nenv MANPATH manuals:\n```\n\nIt this variable does not exists, or it's not valid, SamaruX will search the manual files in the current working directory.\n\nIf you prefix the filename with a directory, Samarux will search the manual file there:\n\n```\nman mescc:help stdio\n```\n\nYou can force SamaruX to search a manual file in the current working directory, if you prefix the filename with the character `:`, as in:\n\n```\nman :help stdio\n```\n\n## Execution modes\n\nThere are two execution modes:\n- CP/M mode: The SamaruX shell will execute only a command and will return to CP/M.\n- Interactive mode: The SamaruX shell will read and execute your commands from the keyboard, until you return to CP/M.\n\nCP/M mode example:\n\n```\nA\u003esx echo Hello world!\nHello world!\n\nA\u003e\n```\n\nInteractive mode example:\n\n```\nA\u003esx\nSamarux v1.00 / 29 Dec 2014 - (c) FloppySoftware, Spain\n\nCP/M version 2.2\n\n28 built-in commands\n\nHi FloppySoftware welcome to Samarux!\n\n[FloppySoftware at B00:] $ env\nTERM = vt52\nUSER = FloppySoftware\nPROMPT = [%u at %w] %$\n\n[FloppySoftware at B00:] $ exit\n\nA\u003e\n```\n\n## Profiling\n\nWith profiling, you can customize your SamaruX environment.\n\nIts use it's not compulsory, but highly recommended (and useful).\n\nThere are two files for profiling::\n\n- profile.sx: For the interactive mode.\n- profcpm.sx: For the CP/M mode.\n\nAn example of profiling in interactive mode:\n\n```\n# -------------------------- #\n# SAMARUX START-UP PROFILE   #\n# -------------------------- #\nenv TERM vt52\nenv USER FloppySoftware\nenv PROMPT [%u at %w] %$\n#\nalias h history 0\nalias logout exit\n#\necho Hi $USER welcome to Samarux!\necho\n```\n\n## Piping and redirection\n\nWith SamaruX, you can enter useful command lines like:\n\n```\ncat letter.txt | more\ngrep 'Gary Kildall' cpm.txt article.doc news.txt \u003e refs.txt\nls -l *.h *.c \u003e cfiles.txt\nman cat | more\n```\n\n## Command line\n\nYou can separate commands in the same line with the semicolon `;`:\n\n```\nman cp \u003e cp.txt ; clear ; cat cp.txt | more\n```\n\nYou can include environment variables in your command lines:\n\n```\nenv NAME Julius ; echo My name is $NAME\n```\n\nAn argument can contain spaces if it is surrounded by single quotes `'`:\n\n```\nenv NAME 'Julius Smith' ; echo My name is $NAME\n```\n\nSamaruX has a command line history facility.\n\nTo see the history, just type:\n\n```\nhistory\n```\n\nAnd the history command will reply something like:\n\n```\n[FloppySoftware at B00:] $ history\n0: cat manual.doc | more\n1: ed letter.txt\n2: ls *.c\n3: man cat\n```\n\nTo select a history command entry, just type its number:\n\n```\nhistory 2\n```\n\nAnd the shell will present a command line, ready to be edited and / or executed:\n\n```\n[FloppySoftware at B00:] $ ls *.c\n```\n\n## Executing CP/M commands\n\nYou can execute CP/M commands by using the cpm command:\n\n```\ncpm PIP A:=M:*.COM\n```\n\nYou will return to SamaruX, once the CP/M command had finished its work.\n\n## Aliases\n\nYou can make aliases for your most frequently used commands:\n\n```\nalias dirall ls -f\n```\n\nThen, you can enter the defined alias as a single word:\n\n```\ndirall\n```\n\n## Small text editor\n\nSamaruX has the `ed` command, a very humble text editor, but very useful to create and edit small text files in a fast way.\n\n```\n[FloppySoftware at B00:] $ ed profile.sx\nFile :  profile.sx\nLines:  14/48\ned\u003e print\n    0: # -------------------------- #\n    1: # SAMARUX START-UP PROFILE   #\n    2: # -------------------------- #\n    3: # env HOME A00:\n    4: env TERM vt52\n    5: # env TEMP M00:\n    6: env USER FloppySoftware\n    7: env PROMPT [%u at %w] %$\n    8: #\n    9: alias h history 0\n   10: alias logout exit\n   11: #\n   12: echo Hi $USER welcome to Samarux!\n   13: echo\ned\u003e edit 8\n    8: # This is a comment\n```\n\n## Help!\n\nSamaruX has a built-in command named man, to offer on-line help about commands an other topics.\n\nThe help contents is stored in the `samarux.man` file.\n\nAs this file is an ordinary text file with a simple structure, you can even add or modify topics.\n\nTo see the available topics, just type:\n\n```\nman | more\n```\n\nTo read about a topic in particular, say `cat`, just type:\n\n```\nman cat | more\n```\n\nIn addition to this, SamaruX has a built-in command named builtin, that prints the name of all available built-in commands. Just type:\n\n```\nbuiltin\n```\n\n## Batch processing and flow control\n\nWith the batch command, you can process files with commands as if they were typed on the keyboard.\n\nSome other SamaruX commands will help you with flow control in batch processing:\n- `if`\n- `goto`\n- `read`\n- `exit`\n\nAn example:\n\n```\n# ----------- #\n# TEST SCRIPT #\n# ----------- #\n#\necho Test Script\necho ===========\n# Menu:\necho\necho 1 : Option One\necho 2 : Option Two\necho 0 : Exit\necho\necho -n Your choice:\nread OP\necho\nif $OP eq 1 goto One\nif $OP eq 2 goto Two\nif $OP eq 0 goto Exit\necho Bad choice, try again.\ngoto Menu\n# One:\necho Your choice was Option One.\ngoto Menu\n# Two:\necho Your choice was Option Two.\ngoto Menu\n# Exit:\nenv OP\n```\n\nYou can include arguments in batch processing.\n\nIf you have a file named `write.sx` with this contents:\n\n```\necho $1 $2 $3\n```\n\nAnd you type:\n\n```\nbatch write.sx How are you?\n```\n\nThe system will reply with:\n\n```\nHow are you?\n```\n\n## License\n\nCopyright (c) Miguel I. Garcia Lopez / FloppySoftware, Spain\n\n[www.floppysoftware.es](http://www.floppysoftware.es)\n\nThis program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMiguelVis%2Fsamarux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMiguelVis%2Fsamarux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMiguelVis%2Fsamarux/lists"}