manual.txt

; File: legoHDL Manual
; Author: Chase Ruskin
; Modified: 12/18/2021
; Created: 10/19/2021
; Description:
;   The help text for each legoHDL command. Provides the name, synopsis,
;   description, and options. Some examples for specific commands too.
; Usage:
;   All lines with ';' are skipped. Each line beginning with an '*' is evaluated
;   to see what command the following text belongs to. Reads all the way up
;   to the next '*'.
; Notes:
;   specific version = 'v1.0.0' or 'v1_0_0'
;   partial version = 'v1', v1.0'
;   <block> = identifier in V.L.N form
;   block identifier delimiter = '.' - separates an identifier into subsections
;
;   Throughout the document, the word entity/unit may be used. This is synonymous with 
;   the Verilog keyword module. any reference to entity also means module. Using
;   the word entity may be replaced with a better term like: unit, part, chip.

; --- DEVELOPMENT COMMANDS ---


* new
NAME:
        new - Create a new legoHDL block (project)

SYNOPSIS:
        legohdl new <block> [-open] [-remote=<url> [-fork]] [-path=<path>] 
                [-no-template]
        legohdl new <file> -file[=<template-file>] [-force] [-no-open]

DESCRIPTION:
        Create a new HDL project recognized by legoHDL as a "block". The block
        will be created under a new folder at the workspace's local path such
        as <workspace-path>/<block-library>/<block-name>. A git repository will 
        be automatically created, and a bare git remote repository URL can be 
        passed for automatic configuration. If a non-bare remote repository is 
        passed, the block will be created and can be optionally forked using 
        -fork.

        When copying in the template, files hidden within a hidden directory 
        will not be copied. The files a designer would place inside a hidden 
        directory may be extra files that could be initialized later on a 
        per-block basis.
        
        If trying to create a new file and that path already exists, the
        existing file will not be overwritten unless -force is used. Creating 
        new files by default will auto-open in the configured text editor.

OPTIONS:
        <block>
            The project's title. A library and a name must be included, and 
            optionally a vendor can be prepended to the title.

        -open
            Upon creating the block, open it in the configured text-editor.

        -remote=<url>
            A bare remote git repository to be attached to the created block's
            git repository.

        -fork
            Separate the remote repository from the local repository. Do not
            push changes to the original remote.

        -path=<path>
            Overrides the default download path and instead creates block at
            <path> relative to the workspace's local path.

        -no-template
            Do not copy in the configured template folder. The created block
            folder will only contain the necessary Block.cfg file.

        <file>
            The filepath to intialize a new file.

        -file[=<template-file>]
            Initialize a new file within the current block. Specifying 
            <template-file> will copy the template file to the desired directory
            with placeholders correctly replaced. Omitting <template-file> will 
            create a blank file.

        -force
            Overwrite the filepath even if it already exists when initializing a
            file.

        -no-open
            Do not open the newly created file in the configured editor.


* init
NAME:
        init - Initialize a legoHDL block from existing code and block metadata.

SYNOPSIS:
        legohdl init <block> [-remote=<url> [-fork]] [-vendor=<mkrt>] 
                [-summary=<summary>]

DESCRIPTION:
        When the current directory or provided remote repository already is a 
        valid legoHDL block, the <block> is ignored.

        When a remote repository is given and it already is a valid block (i.e. 
        the root directory contains a Block.cfg file), the <block> will be 
        ignored and the actual title will be used. This becomes an equivalent to
        using the 'download' command.

OPTIONS:
        <block>
                :ref:

        -remote=<url>
                :ref:

        -fork
                Do not link to the remote repository and try to push any changes
                to the provided <url>.

        -vendor=<vndr>
                Set the block's vendor. <vendor> must be a valid vendor 
                available in the current workspace.

        -summary=<summary>
                Fill in the summary for the block's metadata. <summary> is a 
                string that describes the current block.


* open
NAME:
        open - Use a text-editor to open a variety of legoHDL-related things

SYNOPSIS:
        legohdl open <block>
        legohdl open [<plugin-alias>] -plugin
        legohdl open <profile-name> -profile
        legohdl open (-template | -settings[=<mode>])
        legohdl open <vendor-name> -vendor

DESCRIPTION:
        :todo:

OPTIONS:
        <block>
                :ref:

        <plugin-alias>
            The alias for the saved custom plugin within legoHDL. It is a 
            user-defined key in settings under "plugins". If the alias's value 
            is a command that references a real existing file, that file will be
            opened.

        -plugin
            The flag to indicate a plugin is trying to be opened. If no 
            <plugin-alias> value is given with this flag, the built-in plugins 
            folder will be opened.

        <profile-name>
            The profile configuration name stored within legoHDL settings. When 
            valid, that profile directory will open.

        -profile
            The flag to indicate a profile is trying to be opened.

        -template
            The flag to indicate the template is trying to be opened. If the
            configured template value in settings is blank, the built-in 
            template folder will be opened.
        
        -settings[=<mode>]
            The flag to indicate the settings are trying to be opened.

            <mode> determines how to open the settings. Accepted values are gui 
            and file. When omitted, the default is to open the settings in gui 
            mode.

               
* get
NAME:
        get - Print the compatible code for the ports list of a specified unit

SYNOPSIS:
        legohdl get [<block>:]<unit> [-comp[=<lang>]] [-inst[=<lang>]] [-arch]
                [-edges] [-D | -I] [-no-about]

DESCRIPTION:
        When trying to access current block-level entities, the <block>
        can be omitted (a form of shortcutting). To reference a unit,
        <vendor>.<library>.<project>:<unit>.

        By default, it will print the 'about' section and the component 
        declaration for VHDL entities or the module interface for Verilog 
        modules. This is the comment header block found at the beginning of this
        unit's file (if exists). Helpful to read more information about an unit 
        and how it behaves (if a developer wrote one).

        If -comp is present when -inst is also present and the language 
        outputted is VHDL, the returned VHDL instantiation code will be a 
        component instantiation. If -comp is omitted in this scenario, 
        the returned VHDL instantiation code will be a direct entity 
        instantiation.

        The <lang> assignment from -inst has higher precedence of the <lang>
        assignemnt from -comp when both are present.

OPTIONS:
        <block>
                The block's title. If omitted, the <entity> is searched for only
                within the current block's scope.

        <unit>
                The design unit name. For VHDL this is a package or entity, and
                for Verilog this is a module.

        -comp[=<lang>]
                Print the component declaration. For Verilog language, the 
                module interface is printed instead of a component declaration.

                <lang> specifies what HDL language to use to print the formatted
                code. Accepted values are vlog and vhdl. Omitting <lang> prints 
                the code in the entity's original language.

        -inst[=<lang>]
                Print the direct entity instantiation (VHDL-93 feature) or 
                component instantiation. This includes relevant constants for 
                each generic, relevant signals for each port, and the 
                instantiation code. 
                
                <lang> specifies what HDL language to use to print the formatted
                code. Accepted values are vlog and vhdl. Omitting <lang> prints 
                the code in the unit's original language.

        -arch
                List the available architectures. If the unit is a Verilog
                module, only "rtl" will be listed.
        
        -edges
                Print the units are required by this unit and print the units 
                that integrate this unit into their design. Gets the edges from
                the hierarchical graph.

        -D
                Search the downloaded blocks to get this unit, regardless of
                the status of 'multi-develop'.

        -I
                Search the installed blocks to get this unit, regardless of 
                the status of 'multi-develop'.

        -no-about
                Do not print the 'about' section for the given design unit.


* graph
NAME:
        graph - Visualize the dependency tree for the design

SYNOPSIS:
        legohdl graph [<entity>] [-tb=<tb> | -ignore-tb] [-expand] [-disp-full]

DESCRIPTION:
        Create and view the dependency tree for the current block design. This 
        command is provided as a guide to quickly help the designer see how the
        design unfolds.

        When no <entity> is given, the top-level will be auto-detected and the
        user will be prompted to select one if multiple exist. When -ignore-tb 
        and -tb=<tb> are absent, the testbench for the top-level entity will be 
        auto-detected, if one exists. The user will be prompted to select one if
        multiple exist.

        By default, the graph is in compression mode and will create reference points
        when a duplicate branch occurs. Raising -expand will explicitly display all
        branches without reference points.

OPTIONS:
        <entity>
                The design unit to request as top-level.

        -tb=<tb>
                The relevant testbench file to explicitly include in the 
                dependency tree. Has higher precedence of -ignore-tb.
        
        -ignore-tb
                Do not include any testbench unit in the dependency tree.

        -expand
                Decompress reference points into their duplicate branchs.

        -disp-full
                Display full block identifiers for each unit.


* export
NAME:
        export - Generate a blueprint file or VHDL package file

SYNOPSIS:
        legohdl export [<unit>] [-tb=<tb> | -ignore-tb] [-quiet] [-no-clean]
                [-all]
        legohdl export -pack[=<file>] [-omit=<units>] [-inc=<units>]

DESCRIPTION:
        -ignore-tb has higher precedence than when a <tb> is stated.

        For generating a VHDL package file, passing -inc will ignore -omit if it
        is passed to the command-line as well. -inc has higher precedence than 
        -omit.

        The default VHDL package file name is the block's project name appended
        with '_pkg', and its path will be located at the same directory of the
        Block.cfg file. Override its location and name by entering a <file>.
        Testbench units (design units with no port interfaces) are always
        omitted.

OPTIONS:
        <unit>
                The design unit to request as top-level. All relevant HDL files
                will stem from this unit's file.
        
        -tb=<tb>
                Explicitly request what top-level simulation file to include in
                the blueprint.
                
        -ignore-tb
                Do not include a testbench file in the blueprint.

        -quiet
                Do not print intermediate information while the blueprint file 
                is being created.

        -no-clean
                Do not delete the build/ directory when writing the blueprint.

        -all
                Add all block-level source files and their dependencies.

        -pack[=<file>]
                Create a VHDL package file with component declarations for the 
                current block. Optionally add a relative path and file name for
                <file>.

        -omit=<units>
                Specific list of units to exclude when generating the package 
                file. <units> is a list separated by ','.
        
        -inc=<units>
                When given, it will only allow these explicit units to be
                included in the VHDL package file. <units> is a list separated
                by ','.


* build
NAME:
        build - Execute a custom backend plugin/tool command

SYNOPSIS:
        legohdl [build] +<plugin-alias> [<plugin-args...>]

DESCRIPTION:
        :todo:

OPTIONS:
        <plugin-alias>
                The alias for the saved custom plugin within legoHDL. It will 
                execute the command as if it was called through the terminal.

        <plugin-args...>
                Any additonal arguments to pass directly to the called command.
                All arguments after <plugin-alias> will be passed to the 
                executed command.


* release
NAME:
        release - Set a newer version for the current block

SYNOPSIS:
        legohdl release <version> [-msg=<msg>] [-strict] [-dry-run] 
                [-no-changelog] [-no-install]

DESCRIPTION:
        :todo:

OPTIONS:
        <version>
                The next version for the current block. The value must be either
                major, minor, patch, or an explicit version.

        -msg=<msg>
                The message to commit with. The value for <msg> is a string and
                if the string includes spaces then quotes must encapsulate 
                <msg>. The default message is: "Releases legohdl version
                <version>".

        -strict
                Only adds and commits the modified changelog (if exists) and the
                Block.cfg file. All other uncommitted changes will not be in
                the following release.
        
        -dry-run
                Perform the complete release process as-if the block was to be
                released, but leaves the block unmodified and unreleased.

        -no-install
                Will not automatically install the latest version to the cache.

        -no-changelog
                Skip auto-opening a changelog file (if exists) during the
                release process.


* del
NAME:
        del - Remove a variety of legoHDL-related things

SYNOPSIS:
        legohdl del <block> [-uninstall]

DESCRIPTION:
        :todo:

OPTIONS:
        :todo:


; --- MANAGEMENT COMMANDS ---


* list
NAME:
        list - View a variety of legoHDL-related things

SYNOPSIS:
        legohdl list [<search>] [[-unit [-all] [-ignore-tb]] | [-D] [-I] [-A]] [-alpha]
        legohdl list [-plugin | -label | -vendor | -workspace | -profile | 
                -template]

DESCRIPTION:
        Retrieves a requested data from the catalog.

        When passing a value for <search>, each subsection of a block's
        identifier can be omitted. With each additionally provided subsection,
        the values shift left to the next subsection. See EXAMPLES for more 
        information.

OPTIONS:
        <search>
                Optional field to narrow the given list by. 

        -unit
                Instead of listing blocks, list the units.

        -alpha
                Organize the list in alphabetical order.

        -I
                Filter only installed blocks or units.

        -D
                Filter only downloaded blocks or units.    

        -A
                Filter only available blocks or units from vendors.

        -all
                Display all units, regardless if they are usable or not
                according to what 'multi-develop' is set to.
        
        -plugin
                Return the list of plugins. Fields are alias and command.

        -label
                Return the list of labels. Fields are label, extensions,
                and global.
        
        -vendor
                Return the list of vendors. Fields are vendor, remote 
                repository, block count, and active.
        
        -workspace
                Return the list of workspaces. Fields are workspace, active, 
                path, and vendors.

        -profile
                Return the list of profiles. Fields are profile, last import, 
                legohdl.cfg, template/, and plugins/.

        -template
                Return the list of all availble files from the current template.
                These files can be referenced exactly as listed when 
                initializing a new file with the 'init' command.

EXAMPLES:
        legohdl list lab0
                Since a vendor is omitted and a library is omitted, all blocks 
                starting with "lab0" in their name are returned.

        legohdl list eel4712c.  
                Since a vendor is omitted and a name is omitted, all blocks 
                starting with "eel4712c" in their library are returned.

        legohdl list uf-ece..
                Since a library is omitted and a name is omitted, all blocks 
                starting with "uf-ece" in their vendor are returned.

        legohdl list ..:mux_2x1 -unit
                All V.L.N subsections are blank, so the entire catalog is 
                searched to see if an unit exists with the name "mux_2x1".


* refresh
NAME:
        refresh - Synchronize local vendor repositories with their remotes

SYNOPSIS:
        legohdl refresh [<vendor> | -all]
        legohdl refresh [<profile> | -all] -profile

DESCRIPTION:
        Checks for updates from vendor remote repositories and pulls them down
        to stay up-to-date.

        If no arguments are given, by default all vendors available to the
        current workspace will try to refresh. If -all is given, every possible
        vendor, even outside workspace availability, will sync with its remote 
        (if exists).

OPTIONS:
        <vendor>
                The name of the known vendor to synchronize.

        -all
                Synchronize all profiles or vendors across all workspaces.

        <profile>
                The name of the profile to syncrhonize.
        
        -profile
                Flag to indicate that a profile is trying to be refreshed.
        

* install
NAME:
        install - Bring a block to the workspace's cache for usage

SYNOPSIS:
        legohdl install <block> [-<version> | -requirements]

DESCRIPTION:

OPTIONS:


* uninstall
NAME:
        uninstall - Remove a block from the workspace's cache

SYNOPSIS:
        legohdl uninstall <block> [-<version>]

DESCRIPTION:
        Removes installed block versions from the workspace cache. 
        
        If -<version> is omitted, then ALL versions for the specified block will
        be removed. Specifying -<version> will only remove it and no others, 
        given it is installed. 
        
        Can also remove groups of versions by passing a partial version to
        -<version>.

OPTIONS:
        <block>
                :ref:
        
        -<version>
                Specific version to uninstall.


* download
NAME:
        download - Bring a block to the local workspace for development

SYNOPSIS:
        legohdl download (<block> | (<url> [-fork])) [-open] [-path=<path>]

DESCRIPTION:


OPTIONS:
        -path=<path>
            Overrides the default download path and instead creates block at
            <path> relative to the workspace's local path.


* update
NAME:
        update - Get the latest installed block or profile

SYNOPSIS:
        legohdl update <block>
        legohdl update <profile-name> -profile

DESCRIPTION:
        <block>
                :ref:

        <profile-name>
                :todo:

        -profile
                :todo:

OPTIONS:


* info
NAME:
        info - Read detailed information about a block

SYNOPSIS:
        legohdl info <block> [-D | -I | -<version> | -A] [-more] 
                [-vers[=<range>]] [-changelog]
        legohdl info <profile> -profile
        legohdl info <vendor> -vendor

DESCRIPTION:
        By default, will print the metadata about the given block. 
        
        If -vers is applied, it will list all the available versions for 
        installation, and hightlight which versions are installed under the 
        workspace cache.

        If -changelog is applied, only the changelog file will be printed to
        the console (if exists).

OPTIONS:
        <block>
                :ref:

        -D
                Return data from block at the download level, regardless of
                the status of 'multi-develop'.

        -I
                Return data from latest block at the installation level,
                regardless of the status of 'multi-develop'.

        -<version>
                Return data from the block with specified version/partial
                version.
        
        -A
                Return data from the block at the available level.
        
        -more
                Get relevant stats about the block such as the path, project 
                size, design units, and block integrations.

        -vers[=<range>]
                List all available versions for the specified block. <range>
                will constrain the list of versions. Accepted values for <range>
                are I or a version indexing.

        -changelog
                Print the associated changelog with the block.

        <profile>
                :ref:

        -profile
                Indicate that a profile is to be searched for its information.

        <vendor>
                :ref:
        
        -vendor
                Indicate that a vendor is to be searched for its information.


* config
NAME:
        config - Edit/modify legoHDL settings

SYNOPSIS:
        legohdl config <profile-name> [-ask]
        legohdl config [-<keypath>[(+ | -)]=<value>] [-<sectionpath>]

DESCRIPTION:
        :todo:

OPTIONS:
        <profile-name>
                An existing profile to import settings from.
        
        -ask
                Prompts the user before each import step (settings, template, 
                plugins) if the following should be imported and overloaded.

        :todo:


*