# HDL workflow
-This section describes the workflow for developing the LibreSoC. We use nmigen, yosys and symbiyosys, and this page is intended not just to help you get set up, it is intended to help advise you of dome tricks and practices that will help you become effective team contributors.
+This section describes the workflow for developing the LibreSoC. We use nmigen, yosys and symbiyosys, and this page is intended not just to help you get set up, it is intended to help advise you of some tricks and practices that will help you become effective team contributors.
It is particularly important to bear in mind that we are not just "developing code", here: we are creating a "lasting legacy educational resource" for other people to learn from, and for businesses and students alike to be able to use, learn from and augment for their own purposes.
RAM is the biggest requirement. Minimum 16GB, the more the better (32 or 64GB starts to reach "acceptable" levels. Disk space is not hugely critical: 256GB SSD should be more than adequate. Simulations and FPGA compilations however are where raw processing power is a must. High end Graphics Cards are nonessential.
-What is particularly useful is to have not only hi-res screens (curved is *strongly* recommended if the LCD is over 24in wide), but to have several of them: the more the better. Either a DisplayLink UD160A (or more modern variant) or simply using a second (lower spec hardware) machine is really effective.
+What is particularly useful is to have not only hi-res screens (curved is *strongly* recommended if the LCD is over 24in wide, to avoid eyeballs going "prism"), and to have several of them: the more the better. Either a DisplayLink UD160A (or more modern variant) or simply using a second (lower spec hardware) machine is really effective.
-Also it is really recommended to have a UHD monitor (4k - 3840x2160), or at least 2560x1200. However, caveat below: please when editing do not assume that everyone will have access to such high resolution screens.
+Also it is really recommended to have a UHD monitor (4k - 3840x2160), or at least 2560x1200. If given a choice, 4:3 aspect ratio is better than 16:9 particularly when using several of them. However, caveat (details below): please when editing do not assume that everyone will have access to such high resolution screens.
# Operating System
-First install and become familiar with Debian (ubuntu if you absolutely must) for standardisation cross-team and so that toolchain installation is greatly simplified. yosys in particular warns that trying to use Windows or MacOS will get you into a world of pain.
+First install and become familiar with Debian (ubuntu if you absolutely must) for standardisation cross-team and so that toolchain installation is greatly simplified. yosys in particular warns that trying to use Windows, *BSD or MacOS will get you into a world of pain.
Only a basic GUI desktop is necessary: fvwm2, xfce4, lxde are perfectly sufficient (alongside wicd-gtk for network management). Other more complex desktops can be used however may consume greater resources.
Once this becomes necessary, it it turn implies that having greater than 80 chars per line - and running editors fullscreen -is a severe hindance to an essential *and highly effective* workflow technique.
-Additionally, care should be taken to respect that not everyone will have 200 column editor windows. They may only have a 1280 x 800 laptop which barely fits 2 80x60 xterms side by side. Consequently, having excessively long functions is also a hindrance to others, as such developers with limited screen resources would need to continuously page-up and page-down to read code even of a single function, in full.
+Additionally, care should be taken to respect that not everyone will have 200+ column editor windows. They may only have a 1280 x 800 laptop which barely fits 2 80x53 xterms side by side. Consequently, having excessively long functions is also a hindrance to others, as such developers with limited screen resources would need to continuously page-up and page-down to read the code even of a single function, in full.
This helps explain in part, below, why compliance with pep8 is enforced, including its 80 character limit. In short: not everyone has the same "modern" GUI workflow or has access to the same computing resources as you, so please do respect that.
* **do not commit autogenerated output**. write a shell script and commit that, or add a Makefile to run the command that generates the output, but **do not** add the actual output of **any** command to the repository. ever. this is really important. even if it is a human-readable file rather than a binary object file.
* if the command needed to create any given autogenerated output is not currently in the list of dependencies, first consult on the list if it is okay to make that command become a hard dependency of the project (hint: java, node.js php and .NET commands will cause delays in responses due to list participants laughing hysterically too much), and after a decision is made, document the dependency and how its source code is obtained and built.
+* if you find yourself repeating commands regularly, chances are high that someone else will need to run them, too. therefore, put them into a .sh shell script (and/or a Makefile) and document them at the very minimum in README or INSTALL.txt or somewhere in a docs folder as appopriate. if unsure, ask on the mailing list for advice.
* plan in advance to write not just code but a full test suite for that code. **this is not optional**. large python projects that do not have unit tests **FAIL**.
* edit files making minimal *single purpose* modifications.
* prior to committing make sure that relevant unit tests pass, or that the change is a zero-impact addition.
-* commit no more than 5 to 10 lines at a time, with a CLEAR message (no "added this" or "changed that"). if the commit involves a list of changes or the word "and" it is a "red flag" that the commit has not been properly broken down.
+* commit no more than 5 to 10 lines at a time, with a CLEAR message (no "added this" or "changed that").
+* if the commit message involves a list of changes or the word "and", then STOP. do not proceed: it is a "red flag" that the commit has not been properly broken down. ask for advice on-list.
* if it is essential to commit large amounts of code, ensure that it is **not** in use **anywhere** by any other code.
the reason for the above is because python is a weakly typed language. make one tiny change at the base level of the class hierarchy and the effect may be disastrous.
+therefore, if you are absolutely certain that a new addition (new file, new class, new function) is not going to have any side-effects, committing it (a large amount of code) is perfectly fine.
+
+as a general rule, however, do not use this an an excuse to write code first then write unit tests as an afterthought. write *less* code *in conjunction* with its (more basic) unit tests, instead.
+
* all code needs to conform to pep8. use either pep8checker or better run autopep8. however whenever committing whitespace changes, *make a separate commit* with a commit message "whitespace" or "autopep8 cleanup".
* pep8 REQUIRES no more than 80 chars per line. this is non-negotiable. if you think you need greater than 80 chars, it *fundamentally* indicates poor code design. split the code down further into smaller classes and functions.
* TBD there is a docstring checker. at the minimum make sure to have an SPD license heafer, module header docstring, class docstring and function docstrings on non-obvious functions
projects / libreriscv.git / commitdiff