github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/gen/user-guide/modules_doc.yaml (about)

     1  - DocumentID: modules
     2    Title: >-
     3      Modules and Packages
     4    CategoryID: user-guide
     5    Summary: >-
     6      An introduction to Murex modules and packages
     7    Description: |-
     8      ## Description
     9      
    10      Murex has it's own module system with namespacing and a package manager. But
    11      why should a shell need all this?
    12  
    13      The answer comes from years of me using Bash and wishing my Bash environment
    14      could be consistent across multiple machines. So this document is authored from
    15      the perspective of my personal usage ("me" being Laurence Morgan, the original
    16      author of Murex).
    17  
    18      What Murex's package system provides is:
    19  
    20      1. A way to ensure consistency across multiple platforms
    21      2. An easy way to extend Murex
    22      3. An easy way to share what you've extended with others
    23      4. An easy way to ensure your extensions are kept up-to-date
    24      5. An easy way to track what code is running in your shell and from where it
    25         was loaded
    26  
    27      Before I address those points in more detail, a bit of background into what
    28      modules and packages are:
    29  
    30      ### What Are Packages And Modules?
    31  
    32      {{ include "gen/includes/package-modules.inc.md" }}
    33  
    34      ## Using Packages And Modules
    35  
    36      ### Consistency
    37  
    38      Package database are stored locally at `~/.murex_modules/packages.json`. This
    39      file is portable so any new machine can have `packages.json` imported. The
    40      easiest way of doing this is using `murex-package` which can import from a
    41      local path or HTTP(S) URI and automatically download any packages described in
    42      the database.
    43  
    44      For example the command I run on any new dev machine to import all of my DevOps
    45      tools and terminal preferences is the following:
    46  
    47      ```
    48      murex-package import https://gist.githubusercontent.com/lmorg/770c71786935b44ba6667eaa9d470888/raw/fb7b79d592672d90ecb733944e144d722f77fdee/packages.json
    49      ```
    50  
    51      ### Extendability
    52  
    53      Namespacing allows for `private` functions which allows you to write smaller
    54      functions. Smaller functions are easier to write tests against (Murex also
    55      has an inbuilt testing and debugging tools).
    56  
    57      ### Sharing Code
    58  
    59      Packages can be hosted via HTTP(S) or git. Anyone can import anyone elses
    60      packages using `murex-package`. 
    61  
    62      ```
    63      murex-package install https://github.com/lmorg/murex-module-murex-dev.git
    64      ```
    65  
    66      ### Updating Packages
    67  
    68      Updating packages is easy:
    69  
    70      ```
    71      murex-package update
    72      ```
    73  
    74      ### Tracking Code
    75  
    76      All code loaded in Murex, every function, variable and event (etc) is stored
    77      in memory with metadata about where it was loaded from; which package, file and
    78      at what time. This is called `FileRef`.
    79  
    80      For more information on `FileRef` see the link below.
    81  
    82      {{ include "gen/includes/fileref-module-strings.inc.md" }}
    83    Synonyms:
    84      - module
    85      - modules
    86      - package
    87      - packages
    88    Related:
    89    - murex-package
    90    - fileref
    91    - private
    92    - test
    93    - source