VeriSnip 0.0.2__tar.gz

verisnip-0.0.2/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Pedro Antunes
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

verisnip-0.0.2/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: VeriSnip
+Version: 0.0.2
+Summary: A small example package
+Author-email: Pedro Nuno de Melo Antunes <pedronmantunes@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/LogicoreDesign/VT-Tool.git
+Project-URL: Issues, https://github.com/LogicoreDesign/VT-Tool/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+## VeriSnip-Overview
+
+VeriSnip (VS) is a project designed to bring the power of Verilog scripting to the open‑source hardware community. This tool simplifies the generation of Verilog modules or snippets by seamlessly integrating with other programs. The generated files can be easily included in any Verilog project. The motivation behind this work is so that creating hardware modules is a process of creating a template file written in Verilog and letting your programs/scripts generate the hardware. These scripts are included in your Verilog template file using Verilog snippets.
+
+With VeriSnip, the process of calling programs or scripts responsible for generating Verilog files is streamlined. After file generation, VeriSnip neatly organizes all Hardware Description Languages (HDL) and TestBench files under the build directory.
+
+Learn more about how VeriSnip works [here](#how-to-use-verisnip).
+
+### Index
+
+1. [How to use VeriSnip (*vs\_build.py*)](#how-to-use-verisnip)
+2. [*vs\_colours.py*](#vtcolors)
+3. [MyLibrary](#mylibrary)
+4. [Opening Issues](#opening-an-issue)
+5. [Contributing](#contributing)
+6. [Development Environment](#development-environment)
+7. [Credits](#credits)
+
+## How to use VeriSnip (aka, *vs\_build*)
+
+The ***vs\_build*** script serves as the cornerstone of the VeriSnip tool‑chain, encompassing core functions essential for project compilation. This script orchestrates the creation of the build directory, housing Verilog modules and headers crucial for the project's hardware implementation.
+The code residing under the `./build` directory represents the compiled output ready for simulation and FPGA synthesis.
+
+### Run *vs\_build.py*
+
+***vs\_build*** must receive at least one argument.
+To show the help page:
+
+> Usage: python *vs\_build*.py --help
+
+Create a build directory containing all the compiled hardware:
+
+> Usage: python *vs\_build*.py \<main\_module> --TestBench \<testbench\_name> --Boards \<board\_modules>
+> \<main\_module> -> This is the name of the main RTL design.
+> \--TestBench \<testbench\_name> (optional) -> by default *vs\_build* looks for a TestBench file with the name \<main\_module>\_tb.
+> \--Boards \<board\_modules> (optional) -> by default *vs\_build* looks for NO board RTL design top module. Multiple boards can be passed in a single argument (example, "Board1 Board2 Board3").
+> \--quiet (optional) -> suppresses INFO prints.
+> \--debug (optional) -> enables DEBUG prints.
+
+Clean the contents generated by *vs\_build*:
+
+> Usage: python *vs\_build*.py --clean all
+> all (optional) -> By default "--clean" only removes the "build" directory, with "all" it also removes the "hardware/generated" directory.
+
+Example of calling ***vs\_build***:
+`python3 ./*vs_build* top_module --TestBench top_module_tb --Boards "top_module_ecp5"`
+or
+`./*vs_build* --help`
+
+### Using Verilog Snippets (.vs)
+
+To enable VeriSnip to search for or generate a Verilog Snippet, users only need to include the corresponding ".vs" file in their Verilog modules. For example:
+
+```
+module example (
+  `include "example_ios.vs" // Argument passed to the program/script that generates example_ios.vs
+);
+  `include "example_contents.vs" /*
+    Argument passed to the program/script that generates example_contents.vs
+  */
+endmodule
+```
+
+In the above example, VeriSnip scans for a program or script resembling the Verilog Snippet name (without the file extension). Snippet files must adhere to the snake\_case naming convention, which VeriSnip uses to identify the program/script generating the Snippet file. For instance, the `include "example_ios.vs"` statement corresponds to a program/script named either "example\_ios.*" or "example.*", where \* represents any supported file extension. Similarly, `include "example_contents.vs"` corresponds to "example\_contents.*" or "example.*".
+
+For another example, refer to the [MyReg module](MyLibrary/modules/MyReg.v). You can run `python3 *vs_build* myreg` to execute a small build with VeriSnip.
+
+**Note:** Avoid including a file in the first line of the file, as this is not supported. Instead, use the file's beginning to provide a brief introduction about its contents.
+
+### Creating a Compatible Program/Script for Verilog Snippet Generation
+
+Users have the flexibility to create custom programs or scripts for generating ".vs" files or Verilog modules, or they can utilize existing ones. It's crucial to note that all scripts responsible for generating Verilog code, whether modules or ".vs" files, are independent of "*vs\_build*." "*vs\_build*" exclusively calls these scripts without importing them into the project.
+
+**Supported File Extensions and Corresponding Languages:**
+Currently, VeriSnip supports programs and scripts with the following file extensions:
+
+* ".py" for Python
+* ".sh" for Bash
+* ".lua" for Lua
+* ".scala" for Scala
+* ".rb" for Ruby
+* ".pl" for Perl
+* ".vt" for Verilog Template (a custom extension)
+
+The Verilog Template extension (".vt") is specific to VeriSnip. If you compile a program that generates a Verilog module or snippet, you can use the ".vt" extension to enable VeriSnip to locate it.
+
+When *vs\_build* calls another program ([see example here](*vs_build*.py#L238)), it passes a variable number of arguments. Nevertheless, it always follows the same order. Therefore, take into consideration the following arguments and their order when developing your program or script:
+
+* Path to the program or script being called
+* Difference between the ".vs" filename and the program/script name. It corresponds to the suffix of the program/script name
+* Comment written after the "\`include"
+* File where the include is being called from, therefore the file where the "\`include" is written
+* *vs\_build* received arguments (excluding its own name)
+
+### Code structure
+
+***vs\_build*** code is distinctly divided into three stages.
+
+* in **1st stage** the function `find_vs_scripts_and_verilog()` finds all existing verilog modules, headers, snippets and scripts under the current directory.
+* the **2nd stage** is where it finds the verilog modules and snippets needed by the core. If a verilog module or a snippet does not exist it will try to generate them. The generated snippets should be stored under the `./rtl/generated` directory. The function called for this stage is `verilog_fetch()`.
+* during the **3rd stage** all verilog snippet files included are substituted for its content. Those files are then stored under the `./build` directory.
+
+#### **2nd stage** - details
+
+* When calling scripts to generate ".vs" priority is always given to scripts with the full name of the file. If there is no script corresponding to the ".vs" name look for a script that corresponds only to the initial part of the name. Example:
+
+  * in `include "io_modules.vs"` look for `VTio.py` or `io.py` if `io_modules.py` does not exist.
+* When calling scripts that generate modules the script should have the name of the module.
+* "*vs\_build*" only calls the scripts if they are newer than the files already existent.
+* When there are two or more scripts with the same name a warning should be printed and the script with the closest directory path should be used.
+* All files and scripts should only be looked for from the base directory of the project, unless specified otherwise in a custom script.
+
+#### **3rd stage** - details
+
+* all files which are generated should have a copy in the "aux" directory
+* "*vs\_build*" substitutes the ".vs" and copies the modules needed to the build directory, after finding or generating all modules and ".vs" files.
+
+## *vs\_colours*
+
+This script defines the colors that should be used when printing error, warning or successful messages.
+It defines the `print_coloured()` function and some variables that allow to modify the text printed to the console.
+
+## MyLibrary
+
+The "MyLibrary" directory contains hardware Verilog modules, snippets and scripts that might be commonly reused.
+
+### Scripts
+
+This section of the README contains information about the scripts present under the `./library/scripts` directory.
+Read more about each script in the [README.md on the scripts directory](https://github.com/PedroAntunes178/VT-Tool/tree/main/MyLibrary/scripts/README.md).
+
+## Opening an Issue
+
+Welcome to our issue reporting system! We appreciate your contribution to the project by reporting any issues you encounter. Your feedback helps us make this project even better.
+
+### How to Open an Issue
+
+When opening an issue, please follow this format:
+
+> **Issue Title**: A concise and descriptive title for the issue.
+
+> Hello **Tag the developers you think might be able to help**,
+>
+> ## Issue Description:
+>
+> Provide a detailed description of the issue you encountered. Include information about your environment, steps to reproduce the issue, and any error messages. The more details you provide, the easier it is for us to understand and address the problem.
+>
+> ## Solution Reference (Optional):
+>
+> If you have a solution in mind, you're welcome to present it and provide a detailed explanation of why you believe it will work. If possible, include references to supporting pages or documentation that back your proposed solution. This can help us better understand your perspective and expedite the resolution process.
+>
+> ## Suggested Changes (Optional):
+>
+> If you have ideas for changes that might solve the issue, propose them here. Be clear and concise in your suggestions.
+>
+> ## Additional Question (Optional):
+>
+> If you have questions directly or indirectly related to the issue, feel free to ask them in this section.
+
+Tag developers by using `@username` to get their attention.
+
+We appreciate your help in improving this project!
+
+## Contributing
+
+All contributions to this project are warmly welcomed.
+
+Contributions in the form of automatically generated Verilog scripts should be placed within the hardware/scripts directory. Additionally, contributors are required to create a corresponding section in the README when adding a script. This section should detail the generated core and provide instructions on the script's usage. It is important that the section structure aligns with the structures of other script sections.
+
+## Development Environment
+
+To utilize *vs\_build*, all that's necessary is Python3 and support for the scripting languages in which your scripts are written.
+
+## Credits
+
+This project idea came to me while I was working at IObundle. IObundle was developing a similar open-source tool called python-setup. The two projects are fundamentally different. Therefore I decided to create this project from 0 instead of contributing the ideas and tools directly to IObundle's python-setup.
+
+Where the two projects are similar is both are being developed to generate automatic verilog.
+
+Where they mainly differ is on the way the verilog is generated. The IObundle python-setup project aims to generate all the verilog core using a python framework. VeriSnip aims to substitute the .vs files present on the verilog code, generating the .vs code as needed. There may also exist scripts that generate .v modules.

verisnip-0.0.2/README.md

@@ -0,0 +1,180 @@
+## VeriSnip-Overview
+
+VeriSnip (VS) is a project designed to bring the power of Verilog scripting to the open‑source hardware community. This tool simplifies the generation of Verilog modules or snippets by seamlessly integrating with other programs. The generated files can be easily included in any Verilog project. The motivation behind this work is so that creating hardware modules is a process of creating a template file written in Verilog and letting your programs/scripts generate the hardware. These scripts are included in your Verilog template file using Verilog snippets.
+
+With VeriSnip, the process of calling programs or scripts responsible for generating Verilog files is streamlined. After file generation, VeriSnip neatly organizes all Hardware Description Languages (HDL) and TestBench files under the build directory.
+
+Learn more about how VeriSnip works [here](#how-to-use-verisnip).
+
+### Index
+
+1. [How to use VeriSnip (*vs\_build.py*)](#how-to-use-verisnip)
+2. [*vs\_colours.py*](#vtcolors)
+3. [MyLibrary](#mylibrary)
+4. [Opening Issues](#opening-an-issue)
+5. [Contributing](#contributing)
+6. [Development Environment](#development-environment)
+7. [Credits](#credits)
+
+## How to use VeriSnip (aka, *vs\_build*)
+
+The ***vs\_build*** script serves as the cornerstone of the VeriSnip tool‑chain, encompassing core functions essential for project compilation. This script orchestrates the creation of the build directory, housing Verilog modules and headers crucial for the project's hardware implementation.
+The code residing under the `./build` directory represents the compiled output ready for simulation and FPGA synthesis.
+
+### Run *vs\_build.py*
+
+***vs\_build*** must receive at least one argument.
+To show the help page:
+
+> Usage: python *vs\_build*.py --help
+
+Create a build directory containing all the compiled hardware:
+
+> Usage: python *vs\_build*.py \<main\_module> --TestBench \<testbench\_name> --Boards \<board\_modules>
+> \<main\_module> -> This is the name of the main RTL design.
+> \--TestBench \<testbench\_name> (optional) -> by default *vs\_build* looks for a TestBench file with the name \<main\_module>\_tb.
+> \--Boards \<board\_modules> (optional) -> by default *vs\_build* looks for NO board RTL design top module. Multiple boards can be passed in a single argument (example, "Board1 Board2 Board3").
+> \--quiet (optional) -> suppresses INFO prints.
+> \--debug (optional) -> enables DEBUG prints.
+
+Clean the contents generated by *vs\_build*:
+
+> Usage: python *vs\_build*.py --clean all
+> all (optional) -> By default "--clean" only removes the "build" directory, with "all" it also removes the "hardware/generated" directory.
+
+Example of calling ***vs\_build***:
+`python3 ./*vs_build* top_module --TestBench top_module_tb --Boards "top_module_ecp5"`
+or
+`./*vs_build* --help`
+
+### Using Verilog Snippets (.vs)
+
+To enable VeriSnip to search for or generate a Verilog Snippet, users only need to include the corresponding ".vs" file in their Verilog modules. For example:
+
+```
+module example (
+  `include "example_ios.vs" // Argument passed to the program/script that generates example_ios.vs
+);
+  `include "example_contents.vs" /*
+    Argument passed to the program/script that generates example_contents.vs
+  */
+endmodule
+```
+
+In the above example, VeriSnip scans for a program or script resembling the Verilog Snippet name (without the file extension). Snippet files must adhere to the snake\_case naming convention, which VeriSnip uses to identify the program/script generating the Snippet file. For instance, the `include "example_ios.vs"` statement corresponds to a program/script named either "example\_ios.*" or "example.*", where \* represents any supported file extension. Similarly, `include "example_contents.vs"` corresponds to "example\_contents.*" or "example.*".
+
+For another example, refer to the [MyReg module](MyLibrary/modules/MyReg.v). You can run `python3 *vs_build* myreg` to execute a small build with VeriSnip.
+
+**Note:** Avoid including a file in the first line of the file, as this is not supported. Instead, use the file's beginning to provide a brief introduction about its contents.
+
+### Creating a Compatible Program/Script for Verilog Snippet Generation
+
+Users have the flexibility to create custom programs or scripts for generating ".vs" files or Verilog modules, or they can utilize existing ones. It's crucial to note that all scripts responsible for generating Verilog code, whether modules or ".vs" files, are independent of "*vs\_build*." "*vs\_build*" exclusively calls these scripts without importing them into the project.
+
+**Supported File Extensions and Corresponding Languages:**
+Currently, VeriSnip supports programs and scripts with the following file extensions:
+
+* ".py" for Python
+* ".sh" for Bash
+* ".lua" for Lua
+* ".scala" for Scala
+* ".rb" for Ruby
+* ".pl" for Perl
+* ".vt" for Verilog Template (a custom extension)
+
+The Verilog Template extension (".vt") is specific to VeriSnip. If you compile a program that generates a Verilog module or snippet, you can use the ".vt" extension to enable VeriSnip to locate it.
+
+When *vs\_build* calls another program ([see example here](*vs_build*.py#L238)), it passes a variable number of arguments. Nevertheless, it always follows the same order. Therefore, take into consideration the following arguments and their order when developing your program or script:
+
+* Path to the program or script being called
+* Difference between the ".vs" filename and the program/script name. It corresponds to the suffix of the program/script name
+* Comment written after the "\`include"
+* File where the include is being called from, therefore the file where the "\`include" is written
+* *vs\_build* received arguments (excluding its own name)
+
+### Code structure
+
+***vs\_build*** code is distinctly divided into three stages.
+
+* in **1st stage** the function `find_vs_scripts_and_verilog()` finds all existing verilog modules, headers, snippets and scripts under the current directory.
+* the **2nd stage** is where it finds the verilog modules and snippets needed by the core. If a verilog module or a snippet does not exist it will try to generate them. The generated snippets should be stored under the `./rtl/generated` directory. The function called for this stage is `verilog_fetch()`.
+* during the **3rd stage** all verilog snippet files included are substituted for its content. Those files are then stored under the `./build` directory.
+
+#### **2nd stage** - details
+
+* When calling scripts to generate ".vs" priority is always given to scripts with the full name of the file. If there is no script corresponding to the ".vs" name look for a script that corresponds only to the initial part of the name. Example:
+
+  * in `include "io_modules.vs"` look for `VTio.py` or `io.py` if `io_modules.py` does not exist.
+* When calling scripts that generate modules the script should have the name of the module.
+* "*vs\_build*" only calls the scripts if they are newer than the files already existent.
+* When there are two or more scripts with the same name a warning should be printed and the script with the closest directory path should be used.
+* All files and scripts should only be looked for from the base directory of the project, unless specified otherwise in a custom script.
+
+#### **3rd stage** - details
+
+* all files which are generated should have a copy in the "aux" directory
+* "*vs\_build*" substitutes the ".vs" and copies the modules needed to the build directory, after finding or generating all modules and ".vs" files.
+
+## *vs\_colours*
+
+This script defines the colors that should be used when printing error, warning or successful messages.
+It defines the `print_coloured()` function and some variables that allow to modify the text printed to the console.
+
+## MyLibrary
+
+The "MyLibrary" directory contains hardware Verilog modules, snippets and scripts that might be commonly reused.
+
+### Scripts
+
+This section of the README contains information about the scripts present under the `./library/scripts` directory.
+Read more about each script in the [README.md on the scripts directory](https://github.com/PedroAntunes178/VT-Tool/tree/main/MyLibrary/scripts/README.md).
+
+## Opening an Issue
+
+Welcome to our issue reporting system! We appreciate your contribution to the project by reporting any issues you encounter. Your feedback helps us make this project even better.
+
+### How to Open an Issue
+
+When opening an issue, please follow this format:
+
+> **Issue Title**: A concise and descriptive title for the issue.
+
+> Hello **Tag the developers you think might be able to help**,
+>
+> ## Issue Description:
+>
+> Provide a detailed description of the issue you encountered. Include information about your environment, steps to reproduce the issue, and any error messages. The more details you provide, the easier it is for us to understand and address the problem.
+>
+> ## Solution Reference (Optional):
+>
+> If you have a solution in mind, you're welcome to present it and provide a detailed explanation of why you believe it will work. If possible, include references to supporting pages or documentation that back your proposed solution. This can help us better understand your perspective and expedite the resolution process.
+>
+> ## Suggested Changes (Optional):
+>
+> If you have ideas for changes that might solve the issue, propose them here. Be clear and concise in your suggestions.
+>
+> ## Additional Question (Optional):
+>
+> If you have questions directly or indirectly related to the issue, feel free to ask them in this section.
+
+Tag developers by using `@username` to get their attention.
+
+We appreciate your help in improving this project!
+
+## Contributing
+
+All contributions to this project are warmly welcomed.
+
+Contributions in the form of automatically generated Verilog scripts should be placed within the hardware/scripts directory. Additionally, contributors are required to create a corresponding section in the README when adding a script. This section should detail the generated core and provide instructions on the script's usage. It is important that the section structure aligns with the structures of other script sections.
+
+## Development Environment
+
+To utilize *vs\_build*, all that's necessary is Python3 and support for the scripting languages in which your scripts are written.
+
+## Credits
+
+This project idea came to me while I was working at IObundle. IObundle was developing a similar open-source tool called python-setup. The two projects are fundamentally different. Therefore I decided to create this project from 0 instead of contributing the ideas and tools directly to IObundle's python-setup.
+
+Where the two projects are similar is both are being developed to generate automatic verilog.
+
+Where they mainly differ is on the way the verilog is generated. The IObundle python-setup project aims to generate all the verilog core using a python framework. VeriSnip aims to substitute the .vs files present on the verilog code, generating the .vs code as needed. There may also exist scripts that generate .v modules.

verisnip-0.0.2/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "VeriSnip"
+version = "0.0.2"
+authors = [
+  { name="Pedro Nuno de Melo Antunes", email="pedronmantunes@gmail.com" },
+]
+description = "A small example package"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+
+
+[project.urls]
+Homepage = "https://github.com/LogicoreDesign/VT-Tool.git"
+Issues = "https://github.com/LogicoreDesign/VT-Tool/issues"
+
+[project.scripts]
+vs_build = "VeriSnip.vs_build:main"

verisnip-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+