github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/user-guide/modules.md (about)

     1  # Modules and Packages
     2  
     3  > An introduction to Murex modules and packages
     4  
     5  ## Description
     6  
     7  Murex has it's own module system with namespacing and a package manager. But
     8  why should a shell need all this?
     9  
    10  The answer comes from years of me using Bash and wishing my Bash environment
    11  could be consistent across multiple machines. So this document is authored from
    12  the perspective of my personal usage ("me" being Laurence Morgan, the original
    13  author of Murex).
    14  
    15  What Murex's package system provides is:
    16  
    17  1. A way to ensure consistency across multiple platforms
    18  2. An easy way to extend Murex
    19  3. An easy way to share what you've extended with others
    20  4. An easy way to ensure your extensions are kept up-to-date
    21  5. An easy way to track what code is running in your shell and from where it
    22     was loaded
    23  
    24  Before I address those points in more detail, a bit of background into what
    25  modules and packages are:
    26  
    27  ### What Are Packages And Modules?
    28  
    29  Murex comes with it's own package manager to make managing plugins easier.
    30  
    31  The format of the packages is a directory, typically located at `~/.murex_modules`,
    32  which contains one or more murex scripts. Each script can be it's own module.
    33  ie there are multiple modules that can be grouped together and distributed as a
    34  single package.
    35  
    36  The way packages and modules are represented is as a path:
    37      package/module
    38  
    39  `murex-package` is a package management tool for administrating murex modules
    40  and packages.
    41  
    42  | Name                                                         | Summary                                                      |
    43  | ------------------------------------------------------------ | ------------------------------------------------------------ |
    44  | https://github.com/lmorg/murex-module-jump                   | Enables autojump functionalities                             |
    45  | https://github.com/orefalo/murex-module-starship             | starship - The minimal, blazing-fast, and infinitely customizable prompt |
    46  | and [many more](https://github.com/search?q=murex-module-&type=repositories) | Murex modules typically follow the `murex-module-*` naming convention |
    47  
    48  ## Using Packages And Modules
    49  
    50  ### Consistency
    51  
    52  Package database are stored locally at `~/.murex_modules/packages.json`. This
    53  file is portable so any new machine can have `packages.json` imported. The
    54  easiest way of doing this is using `murex-package` which can import from a
    55  local path or HTTP(S) URI and automatically download any packages described in
    56  the database.
    57  
    58  For example the command I run on any new dev machine to import all of my DevOps
    59  tools and terminal preferences is the following:
    60  
    61  ```
    62  murex-package import https://gist.githubusercontent.com/lmorg/770c71786935b44ba6667eaa9d470888/raw/fb7b79d592672d90ecb733944e144d722f77fdee/packages.json
    63  ```
    64  
    65  ### Extendability
    66  
    67  Namespacing allows for `private` functions which allows you to write smaller
    68  functions. Smaller functions are easier to write tests against (Murex also
    69  has an inbuilt testing and debugging tools).
    70  
    71  ### Sharing Code
    72  
    73  Packages can be hosted via HTTP(S) or git. Anyone can import anyone elses
    74  packages using `murex-package`. 
    75  
    76  ```
    77  murex-package install https://github.com/lmorg/murex-module-murex-dev.git
    78  ```
    79  
    80  ### Updating Packages
    81  
    82  Updating packages is easy:
    83  
    84  ```
    85  murex-package update
    86  ```
    87  
    88  ### Tracking Code
    89  
    90  All code loaded in Murex, every function, variable and event (etc) is stored
    91  in memory with metadata about where it was loaded from; which package, file and
    92  at what time. This is called `FileRef`.
    93  
    94  For more information on `FileRef` see the link below.
    95  
    96  ### Module Strings For Non-Module Code
    97  
    98  #### Source
    99  
   100  A common shell idiom is to load shell script files via `source` / `.`. When
   101  this is done the module string (as seen in the `FileRef` structures described
   102  above) will be `source/hash` where **hash** will be a unique hash of the file
   103  path and load time.
   104  
   105  Thus no two sourced files will share the same module string. Even the same file
   106  but modified and sourced twice (before and after the edit) will have different
   107  module strings due to the load time being part of the hashed data.
   108  
   109  #### REPL
   110  
   111  Any functions, variables, events, auto-completions, etc created manually,
   112  directly, in the interactive shell will have a module string of `murex` and an
   113  empty Filename string.
   114  
   115  ## See Also
   116  
   117  * [FileRef](../user-guide/fileref.md):
   118    How to track what code was loaded and from where
   119  * [`murex-package`](../commands/murex-package.md):
   120    Murex's package manager
   121  * [`private`](../commands/private.md):
   122    Define a private function block
   123  * [`source`](../commands/source.md):
   124    Import Murex code from another file of code block
   125  * [`test`](../commands/test.md):
   126    Murex's test framework - define tests, run tests and debug shell scripts
   127  
   128  <hr/>
   129  
   130  This document was generated from [gen/user-guide/modules_doc.yaml](https://github.com/lmorg/murex/blob/master/gen/user-guide/modules_doc.yaml).