Revert "Merge pull request #1917 from YosysHQ/eddie/abc9_delay_check"

[yosys.git] / CodingReadme

diff --git a/CodingReadme b/CodingReadme
index d2e975dab0976ab215e321cb4d536936fdae684d..7d4ded93d2ffb12e88b81d0a254f6b804c6e1127 100644 (file)
--- 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") { }
 
        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;
                        log("Hello World!\n");
                }
        } HelloWorldPass;


@@ -202,6 +202,52 @@ of how to use the Yosys API:
        manual/PRESENTATION_Prog/my_cmd.cc
 
 
        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
 ------------------------------
 
 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
        cd ~yosys
        make clean
        make test

+       make ystests

        make vloghtb
        make install
 
        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
 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"
 
        - 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
 
        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
 ====================
 
 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)
 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:
 
 
 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:
 
   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
 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:
 
 
 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
   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
 
 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 unit-test

-make run-all-unitest

 ```
 
 If you want to remove all unit test files, type:
 ```
 
 If you want to remove all unit test files, type: