X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=CodingReadme;h=7d4ded93d2ffb12e88b81d0a254f6b804c6e1127;hb=63246a5c0eb5780675384d00443e6e46b5e59603;hp=d2e975dab0976ab215e321cb4d536936fdae684d;hpb=3f2f64f41475550527a5621f57d0b0d2b30ee179;p=yosys.git

diff --git a/CodingReadme b/CodingReadme
index d2e975dab..7d4ded93d 100644
--- a/CodingReadme
+++ b/CodingReadme
@@ -21,7 +21,7 @@ Here is a the C++ code for a "hello_world" Yosys command (hello.cc):
 
 	struct HelloWorldPass : public Pass {
 		HelloWorldPass() : Pass("hello_world") { }
-		virtual void execute(vector<string>, Design*) {
+		void execute(vector<string>, Design*) override {
 			log("Hello World!\n");
 		}
 	} HelloWorldPass;
@@ -202,6 +202,52 @@ of how to use the Yosys API:
 	manual/PRESENTATION_Prog/my_cmd.cc
 
 
+Script Passes
+-------------
+
+The ScriptPass base class can be used to implement passes that just call other passes,
+like a script. Examples for such passes are:
+
+	techlibs/common/prep.cc
+	techlibs/common/synth.cc
+
+In some cases it is easier to implement such a pass as regular pass, for example when
+ScriptPass doesn't provide the type of flow control desired. (But many of the
+script passes in Yosys that don't use ScriptPass simply predate the ScriptPass base
+class.) Examples for such passes are:
+
+	passes/opt/opt.cc
+	passes/proc/proc.cc
+
+Whether they use the ScriptPass base-class or not, a pass should always either
+call other passes without doing any non-trivial work itself, or should implement
+a non-trivial algorithm but not call any other passes. The reason for this is that
+this helps containing complexity in individual passes and simplifies debugging the
+entire system.
+
+Exceptions to this rule should be rare and limited to cases where calling other
+passes is optional and only happens when requested by the user (such as for
+example `techmap -autoproc`), or where it is about commands that are "top-level
+commands" in their own right, not components to be used in regular synthesis
+flows (such as the `bugpoint` command).
+
+A pass that would "naturally" call other passes and also do some work itself
+should be re-written in one of two ways:
+
+1) It could be re-written as script pass with the parts that are not calls
+to other passes factored out into individual new passes. Usually in those
+cases the new sub passes share the same prefix as the top-level script pass.
+
+2) It could be re-written so that it already expects the design in a certain
+state, expecting the calling script to set up this state before calling the
+pass in questions.
+
+Many back-ends are examples for the 2nd approach. For example, `write_aiger`
+does not convert the design into AIG representation, but expects the design
+to be already in this form, and prints an `Unsupported cell type` error
+message otherwise.
+
+
 Notes on the existing codebase
 ------------------------------
 
@@ -373,6 +419,7 @@ Finally run all tests with "make config-{clang,gcc,gcc-4.8}":
 	cd ~yosys
 	make clean
 	make test
+	make ystests
 	make vloghtb
 	make install
 
@@ -389,6 +436,7 @@ Finally run all tests with "make config-{clang,gcc,gcc-4.8}":
 Release:
 
 	- set YOSYS_VER to x.y.z in Makefile
+	- remove "bumpversion" target from Makefile
 	- update version string in CHANGELOG
 	git commit -am "Yosys x.y.z"
 
@@ -411,6 +459,32 @@ Updating the website:
 	git commit -am update
 	make push
 
+
+
+Cross-Building for Windows with MXE
+===================================
+
+Check http://mxe.cc/#requirements and install all missing requirements.
+
+As root (or other user with write access to /usr/local/src):
+
+	cd /usr/local/src
+	git clone https://github.com/mxe/mxe.git
+	cd mxe
+
+	make -j$(nproc) MXE_PLUGIN_DIRS="plugins/tcl.tk" \
+			MXE_TARGETS="i686-w64-mingw32.static" \
+			gcc tcl readline
+
+Then as regular user in some directory where you build stuff:
+
+	git clone https://github.com/cliffordwolf/yosys.git yosys-win32
+	cd yosys-win32
+	make config-mxe
+	make -j$(nproc) mxebin
+
+
+
 How to add unit test
 ====================
 
@@ -429,15 +503,15 @@ well with C/C++ code.  Hence, it was chosen (google test)
 relatively easy learn.
 
 Install and configure google test (manually)
-============================================
+--------------------------------------------
 
 In this section, you will see a brief description of how to install google
 test. However, it is strongly recommended that you take a look to the official
 repository (https://github.com/google/googletest) and refers to that if you
 have any problem to install it. Follow the steps below:
 
-* Install: cmake
-* Clone google test project from: //github.com/rodrigosiqueira/logbook.git and
+* Install: cmake and pthread
+* Clone google test project from: https://github.com/google/googletest and
   enter in the project directory
 * Inside project directory, type:
 
@@ -456,7 +530,7 @@ Ps.: Some distros already have googletest packed. If your distro supports it,
 you can use it instead of compile.
 
 Create new unit test
-=======================
+--------------------
 
 If you want to add new unit tests for Yosys, just follow the steps below:
 
@@ -467,19 +541,13 @@ If you want to add new unit tests for Yosys, just follow the steps below:
   unit test for kernel/celledges.cc, you will need to create a file like this:
   tests/unit/kernel/celledgesTest.cc;
 * Implement your unit test
-* If you want to compile your tests, just go to yosys root directory and type:
-```
-make unit-test
-```
 
 Run unit test
-=============
+-------------
 
-To run all unit tests, you need to compile it first and then run it. Follow the
-steps below (from the yosys root directory):
+To compile and run all unit tests, just go to yosys root directory and type:
 ```
 make unit-test
-make run-all-unitest
 ```
 
 If you want to remove all unit test files, type: