From d9ec35a526b9583727ef484ec68bc288dcddb0c8 Mon Sep 17 00:00:00 2001
From: "N. Engelhardt" <nak@yosyshq.com>
Date: Mon, 22 Mar 2021 19:16:25 +0100
Subject: split CodingReadme into multiple files

---
 .clang-format             |   2 +-
 .dockerignore             |   3 +-
 CodeOfConduct             |  73 ------
 CodingReadme              | 556 ----------------------------------------------
 README.md                 |   2 +-
 guidelines/Checklists     | 120 ++++++++++
 guidelines/CodeOfConduct  |  73 ++++++
 guidelines/CodingStyle    |  35 +++
 guidelines/GettingStarted | 249 +++++++++++++++++++++
 guidelines/UnitTests      |  69 ++++++
 guidelines/Windows        |  60 +++++
 kernel/yosys.h            |   2 +-
 manual/CHAPTER_Prog.tex   |  11 +-
 13 files changed, 616 insertions(+), 639 deletions(-)
 delete mode 100644 CodeOfConduct
 delete mode 100644 CodingReadme
 create mode 100644 guidelines/Checklists
 create mode 100644 guidelines/CodeOfConduct
 create mode 100644 guidelines/CodingStyle
 create mode 100644 guidelines/GettingStarted
 create mode 100644 guidelines/UnitTests
 create mode 100644 guidelines/Windows

diff --git a/.clang-format b/.clang-format
index 28d13da25..c86fa8c1c 100644
--- a/.clang-format
+++ b/.clang-format
@@ -6,7 +6,7 @@ BreakBeforeBraces: Linux
 AllowShortIfStatementsOnASingleLine: false
 IndentCaseLabels: false
 
-# From CodingReadme
+# From guidelines/CodingStyle
 TabWidth: 8
 ContinuationIndentWidth: 2
 ColumnLimit: 150
diff --git a/.dockerignore b/.dockerignore
index 9910e9954..9f1da94da 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -6,8 +6,7 @@
 Dockerfile
 README.md
 manual
-CodingReadme
+guidelines
 CodeOfConduct
 .travis
 .travis.yml
-
diff --git a/CodeOfConduct b/CodeOfConduct
deleted file mode 100644
index 4f779977b..000000000
--- a/CodeOfConduct
+++ /dev/null
@@ -1,73 +0,0 @@
-Contributor Covenant Code of Conduct
-
-Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of experience,
-nationality, personal appearance, race, religion, or sexual identity and
-orientation.
-
-Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
-  advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at clifford@clifford.at (and/or
-cliffordvienna@gmail.com if you think your mail to the other address got
-stuck in the spam filter). All complaints will be reviewed and investigated and
-will result in a response that is deemed necessary and appropriate to the
-circumstances. The project team is obligated to maintain confidentiality with
-regard to the reporter of an incident.  Further details of specific enforcement
-policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-Attribution
-
-This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
-available at http://contributor-covenant.org/version/1/4/
diff --git a/CodingReadme b/CodingReadme
deleted file mode 100644
index 7d4ded93d..000000000
--- a/CodingReadme
+++ /dev/null
@@ -1,556 +0,0 @@
-
-This file contains some very brief documentation on things like programming APIs.
-Also consult the Yosys manual and the section about programming in the presentation.
-(Both can be downloaded as PDF from the yosys webpage.)
-
-
---snip-- only the lines below this mark are included in the yosys manual --snip--
-Getting Started
-===============
-
-
-Outline of a Yosys command
---------------------------
-
-Here is a the C++ code for a "hello_world" Yosys command (hello.cc):
-
-	#include "kernel/yosys.h"
-
-	USING_YOSYS_NAMESPACE
-	PRIVATE_NAMESPACE_BEGIN
-
-	struct HelloWorldPass : public Pass {
-		HelloWorldPass() : Pass("hello_world") { }
-		void execute(vector<string>, Design*) override {
-			log("Hello World!\n");
-		}
-	} HelloWorldPass;
-
-	PRIVATE_NAMESPACE_END
-
-This can be built into a Yosys module using the following command:
-
-	yosys-config --exec --cxx --cxxflags --ldflags -o hello.so -shared hello.cc --ldlibs
-
-Or short:
-
-	yosys-config --build hello.so hello.cc
-
-And then executed using the following command:
-
-	yosys -m hello.so -p hello_world
-
-
-Yosys Data Structures
----------------------
-
-Here is a short list of data structures that you should make yourself familiar
-with before you write C++ code for Yosys. The following data structures are all
-defined when "kernel/yosys.h" is included and USING_YOSYS_NAMESPACE is used.
-
-  1. Yosys Container Classes
-
-Yosys uses dict<K, T> and pool<T> as main container classes. dict<K, T> is
-essentially a replacement for std::unordered_map<K, T> and pool<T> is a
-replacement for std::unordered_set<T>. The main characteristics are:
-
-	- dict<K, T> and pool<T> are about 2x faster than the std containers
-
-	- references to elements in a dict<K, T> or pool<T> are invalidated by
-	  insert and remove operations (similar to std::vector<T> on push_back()).
-
-	- some iterators are invalidated by erase(). specifically, iterators
-	  that have not passed the erased element yet are invalidated. (erase()
-	  itself returns valid iterator to the next element.)
-
-	- no iterators are invalidated by insert(). elements are inserted at
-	  begin(). i.e. only a new iterator that starts at begin() will see the
-	  inserted elements.
-
-	- the method .count(key, iterator) is like .count(key) but only
-	  considers elements that can be reached via the iterator.
-
-	- iterators can be compared. it1 < it2 means that the position of t2
-	  can be reached via t1 but not vice versa.
-
-	- the method .sort() can be used to sort the elements in the container
-	  the container stays sorted until elements are added or removed.
-
-	- dict<K, T> and pool<T> will have the same order of iteration across
-	  all compilers, standard libraries and architectures.
-
-In addition to dict<K, T> and pool<T> there is also an idict<K> that
-creates a bijective map from K to the integers. For example:
-
-	idict<string, 42> si;
-	log("%d\n", si("hello"));      // will print 42
-	log("%d\n", si("world"));      // will print 43
-	log("%d\n", si.at("world"));   // will print 43
-	log("%d\n", si.at("dummy"));   // will throw exception
-	log("%s\n", si[42].c_str()));  // will print hello
-	log("%s\n", si[43].c_str()));  // will print world
-	log("%s\n", si[44].c_str()));  // will throw exception
-
-It is not possible to remove elements from an idict.
-
-Finally mfp<K> implements a merge-find set data structure (aka. disjoint-set or
-union-find) over the type K ("mfp" = merge-find-promote).
-
-  2. Standard STL data types
-
-In Yosys we use std::vector<T> and std::string whenever applicable. When
-dict<K, T> and pool<T> are not suitable then std::map<K, T> and std::set<T>
-are used instead.
-
-The types std::vector<T> and std::string are also available as vector<T>
-and string in the Yosys namespace.
-
-  3. RTLIL objects
-
-The current design (essentially a collection of modules, each defined by a
-netlist) is stored in memory using RTLIL object (declared in kernel/rtlil.h,
-automatically included by kernel/yosys.h). You should glance over at least
-the declarations for the following types in kernel/rtlil.h:
-
-	RTLIL::IdString
-		This is a handle for an identifier (e.g. cell or wire name).
-		It feels a lot like a std::string, but is only a single int
-		in size. (The actual string is stored in a global lookup
-		table.)
-
-	RTLIL::SigBit
-		A single signal bit. I.e. either a constant state (0, 1,
-		x, z) or a single bit from a wire.
-
-	RTLIL::SigSpec
-		Essentially a vector of SigBits.
-
-	RTLIL::Wire
-	RTLIL::Cell
-		The building blocks of the netlist in a module.
-
-	RTLIL::Module
-	RTLIL::Design
-		The module is a container with connected cells and wires
-		in it. The design is a container with modules in it.
-
-All this types are also available without the RTLIL:: prefix in the Yosys
-namespace.
-
-  4. SigMap and other Helper Classes
-
-There are a couple of additional helper classes that are in wide use
-in Yosys. Most importantly there is SigMap (declared in kernel/sigtools.h).
-
-When a design has many wires in it that are connected to each other, then a
-single signal bit can have multiple valid names. The SigMap object can be used
-to map SigSpecs or SigBits to unique SigSpecs and SigBits that consistently
-only use one wire from such a group of connected wires. For example:
-
-	SigBit a = module->addWire(NEW_ID);
-	SigBit b = module->addWire(NEW_ID);
-	module->connect(a, b);
-
-	log("%d\n", a == b); // will print 0
-
-	SigMap sigmap(module);
-	log("%d\n", sigmap(a) == sigmap(b)); // will print 1
-
-
-Using the RTLIL Netlist Format
-------------------------------
-
-In the RTLIL netlist format the cell ports contain SigSpecs that point to the
-Wires. There are no references in the other direction. This has two direct
-consequences:
-
-(1) It is very easy to go from cells to wires but hard to go in the other way.
-
-(2) There is no danger in removing cells from the netlists, but removing wires
-can break the netlist format when there are still references to the wire
-somewhere in the netlist.
-
-The solution to (1) is easy: Create custom indexes that allow you to make fast
-lookups for the wire-to-cell direction. You can either use existing generic
-index structures to do that (such as the ModIndex class) or write your own
-index. For many application it is simplest to construct a custom index. For
-example:
-
-	SigMap sigmap(module);
-	dict<SigBit, Cell*> sigbit_to_driver_index;
-
-	for (auto cell : module->cells())
-		for (auto &conn : cell->connections())
-			if (cell->output(conn.first))
-				for (auto bit : sigmap(conn.second))
-					sigbit_to_driver_index[bit] = cell;
-
-Regarding (2): There is a general theme in Yosys that you don't remove wires
-from the design. You can rename them, unconnect them, but you do not actually remove
-the Wire object from the module. Instead you let the "clean" command take care
-of the dangling wires. On the other hand it is safe to remove cells (as long as
-you make sure this does not invalidate a custom index you are using in your code).
-
-
-Example Code
-------------
-
-The following yosys commands are a good starting point if you are looking for examples
-of how to use the Yosys API:
-
-	manual/CHAPTER_Prog/stubnets.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
-------------------------------
-
-For historical reasons not all parts of Yosys adhere to the current coding
-style. When adding code to existing parts of the system, adhere to this guide
-for the new code instead of trying to mimic the style of the surrounding code.
-
-
-
-Coding Style
-============
-
-
-Formatting of code
-------------------
-
-- Yosys code is using tabs for indentation. Tabs are 8 characters.
-
-- A continuation of a statement in the following line is indented by
-  two additional tabs.
-
-- Lines are as long as you want them to be. A good rule of thumb is
-  to break lines at about column 150.
-
-- Opening braces can be put on the same or next line as the statement
-  opening the block (if, switch, for, while, do). Put the opening brace
-  on its own line for larger blocks, especially blocks that contains
-  blank lines.
-
-- Otherwise stick to the Linux Kernel Coding Style:
-    https://www.kernel.org/doc/Documentation/CodingStyle
-
-
-C++ Language
--------------
-
-Yosys is written in C++11. At the moment only constructs supported by
-gcc 4.8 are allowed in Yosys code. This will change in future releases.
-
-In general Yosys uses "int" instead of "size_t". To avoid compiler
-warnings for implicit type casts, always use "GetSize(foobar)" instead
-of "foobar.size()". (GetSize() is defined in kernel/yosys.h)
-
-Use range-based for loops whenever applicable.
-
-
---snap-- only the lines above this mark are included in the yosys manual --snap--
-
-
-Creating the Visual Studio Template Project
-===========================================
-
-1. Create an empty Visual C++ Win32 Console App project
-
-	Microsoft Visual Studio Express 2013 for Windows Desktop
-	Open New Project Wizard (File -> New Project..)
-
-	Project Name: YosysVS
-	Solution Name: YosysVS
-	[X] Create directory for solution
-	[ ] Add to source control
-
-	[X] Console applications
-	[X] Empty Project
-	[ ] SDL checks
-
-2. Open YosysVS Project Properties
-
-	Select Configuration: All Configurations
-
-	C/C++ -> General -> Additional Include Directories
-		Add: ..\yosys
-
-	C/C++ -> Preprocessor -> Preprocessor Definitions
-		Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
-
-3. Resulting file system tree:
-
-	YosysVS/
-	YosysVS/YosysVS
-	YosysVS/YosysVS/YosysVS.vcxproj
-	YosysVS/YosysVS/YosysVS.vcxproj.filters
-	YosysVS/YosysVS.sdf
-	YosysVS/YosysVS.sln
-	YosysVS/YosysVS.v12.suo
-
-4. Zip YosysVS as YosysVS-Tpl-v1.zip
-
-
-
-Checklist for adding internal cell types
-========================================
-
-Things to do right away:
-
-	- Add to kernel/celltypes.h (incl. eval() handling for non-mem cells)
-	- Add to InternalCellChecker::check() in kernel/rtlil.cc
-	- Add to techlibs/common/simlib.v
-	- Add to techlibs/common/techmap.v
-
-Things to do after finalizing the cell interface:
-
-	- Add support to kernel/satgen.h for the new cell type
-	- Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom)
-	- Maybe add support to the Verilog backend for dumping such cells as expression
-
-
-
-Checklist for creating Yosys releases
-=====================================
-
-Update the CHANGELOG file:
-
-	cd ~yosys
-	gitk &
-	vi CHANGELOG
-
-
-Update and check documentation:
-
-	cd ~yosys
-	make update-manual
-	make manual
-	- sanity check the figures in the appnotes and presentation
-	    - if there are any odd things -> investigate
-	    - make cosmetic changes to the .tex files if necessary
-
-	cd ~yosys
-	vi README CodingReadme
-	- is the information provided in those file still up to date
-
-
-Then with default config setting:
-
-	cd ~yosys
-	make vgtest
-
-	cd ~yosys
-	./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
-	./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
-	./yosys -p 'synth; show' tests/simple/fiedler-cooley.v
-	./yosys -p 'synth_xilinx -top up3down5; show' tests/simple/fiedler-cooley.v
-
-	cd ~yosys/examples/cmos
-	bash testbench.sh
-
-	cd ~yosys/examples/basys3
-	bash run.sh
-
-
-Test building plugins with various of the standard passes:
-
-	yosys-config --build test.so equiv_simple.cc
-	- also check the code examples in CodingReadme
-
-
-And if a version of the verific library is currently available:
-
-	cd ~yosys
-	cat frontends/verific/build_amd64.txt
-	- follow instructions
-
-	cd frontends/verific
-	../../yosys test_navre.ys
-
-
-Finally run all tests with "make config-{clang,gcc,gcc-4.8}":
-
-	cd ~yosys
-	make clean
-	make test
-	make ystests
-	make vloghtb
-	make install
-
-	cd ~yosys-bigsim
-	make clean
-	make full
-
-	cd ~vloghammer
-	make purge gen_issues gen_samples
-	make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world
-	chromium-browser report.html
-
-
-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"
-
-	- push tag to github
-	- post changelog on github
-	- post short release note on reddit
-
-
-Updating the website:
-
-	cd ~yosys
-	make manual
-	make install
-
-	- update pdf files on the website
-
-	cd ~yosys-web
-	make update_cmd
-	make update_show
-	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
-====================
-
-Unit test brings some advantages, briefly, we can list some of them (reference
-[1](https://en.wikipedia.org/wiki/Unit_testing)):
-
-* Tests reduce bugs in new features;
-* Tests reduce bugs in existing features;
-* Tests are good documentation;
-* Tests reduce the cost of change;
-* Tests allow refactoring;
-
-With those advantages in mind, it was required to choose a framework which fits
-well with C/C++ code.  Hence, it was chosen (google test)
-[https://github.com/google/googletest], because it is largely used and it is
-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 and pthread
-* Clone google test project from: https://github.com/google/googletest and
-  enter in the project directory
-* Inside project directory, type:
-
-```
-cmake -DBUILD_SHARED_LIBS=ON .
-make
-```
-
-* After compilation, copy all "*.so" inside directory "googlemock" and
-  "googlemock/gtest" to "/usr/lib/"
-* Done! Now you can compile your tests.
-
-If you have any problem, go to the official repository to find help.
-
-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:
-
-* Go to directory "yosys/test/unit/"
-* In this directory you can find something similar Yosys's directory structure.
-  To create your unit test file you have to follow this pattern:
-  fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the
-  unit test for kernel/celledges.cc, you will need to create a file like this:
-  tests/unit/kernel/celledgesTest.cc;
-* Implement your unit test
-
-Run unit test
--------------
-
-To compile and run all unit tests, just go to yosys root directory and type:
-```
-make unit-test
-```
-
-If you want to remove all unit test files, type:
-```
-make clean-unit-test
-```
diff --git a/README.md b/README.md
index 203a292d1..74b6170b1 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ The "Documentation" page on the web site contains links to more resources,
 including a manual that even describes some of the Yosys internals:
 - http://www.clifford.at/yosys/documentation.html
 
-The file `CodingReadme` in this directory contains additional information
+The directory `guidelines` contains additional information
 for people interested in using the Yosys C++ APIs.
 
 Users interested in formal verification might want to use the formal verification
diff --git a/guidelines/Checklists b/guidelines/Checklists
new file mode 100644
index 000000000..cc61c7876
--- /dev/null
+++ b/guidelines/Checklists
@@ -0,0 +1,120 @@
+Checklist for adding internal cell types
+========================================
+
+Things to do right away:
+
+	- Add to kernel/celltypes.h (incl. eval() handling for non-mem cells)
+	- Add to InternalCellChecker::check() in kernel/rtlil.cc
+	- Add to techlibs/common/simlib.v
+	- Add to techlibs/common/techmap.v
+
+Things to do after finalizing the cell interface:
+
+	- Add support to kernel/satgen.h for the new cell type
+	- Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom)
+	- Maybe add support to the Verilog backend for dumping such cells as expression
+
+
+
+Checklist for creating Yosys releases
+=====================================
+
+Update the CHANGELOG file:
+
+	cd ~yosys
+	gitk &
+	vi CHANGELOG
+
+
+Update and check documentation:
+
+	cd ~yosys
+	make update-manual
+	make manual
+	- sanity check the figures in the appnotes and presentation
+	    - if there are any odd things -> investigate
+	    - make cosmetic changes to the .tex files if necessary
+
+	cd ~yosys
+	vi README guidelines/*
+	- is the information provided in those file still up to date
+
+
+Then with default config setting:
+
+	cd ~yosys
+	make vgtest
+
+	cd ~yosys
+	./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
+	./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v
+	./yosys -p 'synth; show' tests/simple/fiedler-cooley.v
+	./yosys -p 'synth_xilinx -top up3down5; show' tests/simple/fiedler-cooley.v
+
+	cd ~yosys/examples/cmos
+	bash testbench.sh
+
+	cd ~yosys/examples/basys3
+	bash run.sh
+
+
+Test building plugins with various of the standard passes:
+
+	yosys-config --build test.so equiv_simple.cc
+	- also check the code examples in guidelines/GettingStarted
+
+
+And if a version of the verific library is currently available:
+
+	cd ~yosys
+	cat frontends/verific/build_amd64.txt
+	- follow instructions
+
+	cd frontends/verific
+	../../yosys test_navre.ys
+
+
+Finally run all tests with "make config-{clang,gcc,gcc-4.8}":
+
+	cd ~yosys
+	make clean
+	make test
+	make ystests
+	make vloghtb
+	make install
+
+	cd ~yosys-bigsim
+	make clean
+	make full
+
+	cd ~vloghammer
+	make purge gen_issues gen_samples
+	make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world
+	chromium-browser report.html
+
+
+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"
+
+	- push tag to github
+	- post changelog on github
+	- post short release note on reddit
+
+
+Updating the website:
+
+	cd ~yosys
+	make manual
+	make install
+
+	- update pdf files on the website
+
+	cd ~yosys-web
+	make update_cmd
+	make update_show
+	git commit -am update
+	make push
diff --git a/guidelines/CodeOfConduct b/guidelines/CodeOfConduct
new file mode 100644
index 000000000..4f779977b
--- /dev/null
+++ b/guidelines/CodeOfConduct
@@ -0,0 +1,73 @@
+Contributor Covenant Code of Conduct
+
+Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at clifford@clifford.at (and/or
+cliffordvienna@gmail.com if you think your mail to the other address got
+stuck in the spam filter). All complaints will be reviewed and investigated and
+will result in a response that is deemed necessary and appropriate to the
+circumstances. The project team is obligated to maintain confidentiality with
+regard to the reporter of an incident.  Further details of specific enforcement
+policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
+available at http://contributor-covenant.org/version/1/4/
diff --git a/guidelines/CodingStyle b/guidelines/CodingStyle
new file mode 100644
index 000000000..d3d3a7134
--- /dev/null
+++ b/guidelines/CodingStyle
@@ -0,0 +1,35 @@
+Coding Style
+============
+
+
+Formatting of code
+------------------
+
+- Yosys code is using tabs for indentation. Tabs are 8 characters.
+
+- A continuation of a statement in the following line is indented by
+  two additional tabs.
+
+- Lines are as long as you want them to be. A good rule of thumb is
+  to break lines at about column 150.
+
+- Opening braces can be put on the same or next line as the statement
+  opening the block (if, switch, for, while, do). Put the opening brace
+  on its own line for larger blocks, especially blocks that contains
+  blank lines.
+
+- Otherwise stick to the Linux Kernel Coding Style:
+    https://www.kernel.org/doc/Documentation/CodingStyle
+
+
+C++ Language
+-------------
+
+Yosys is written in C++11. At the moment only constructs supported by
+gcc 4.8 are allowed in Yosys code. This will change in future releases.
+
+In general Yosys uses "int" instead of "size_t". To avoid compiler
+warnings for implicit type casts, always use "GetSize(foobar)" instead
+of "foobar.size()". (GetSize() is defined in kernel/yosys.h)
+
+Use range-based for loops whenever applicable.
\ No newline at end of file
diff --git a/guidelines/GettingStarted b/guidelines/GettingStarted
new file mode 100644
index 000000000..fcc84c153
--- /dev/null
+++ b/guidelines/GettingStarted
@@ -0,0 +1,249 @@
+Getting Started
+===============
+
+
+Outline of a Yosys command
+--------------------------
+
+Here is a the C++ code for a "hello_world" Yosys command (hello.cc):
+
+	#include "kernel/yosys.h"
+
+	USING_YOSYS_NAMESPACE
+	PRIVATE_NAMESPACE_BEGIN
+
+	struct HelloWorldPass : public Pass {
+		HelloWorldPass() : Pass("hello_world") { }
+		void execute(vector<string>, Design*) override {
+			log("Hello World!\n");
+		}
+	} HelloWorldPass;
+
+	PRIVATE_NAMESPACE_END
+
+This can be built into a Yosys module using the following command:
+
+	yosys-config --exec --cxx --cxxflags --ldflags -o hello.so -shared hello.cc --ldlibs
+
+Or short:
+
+	yosys-config --build hello.so hello.cc
+
+And then executed using the following command:
+
+	yosys -m hello.so -p hello_world
+
+
+Yosys Data Structures
+---------------------
+
+Here is a short list of data structures that you should make yourself familiar
+with before you write C++ code for Yosys. The following data structures are all
+defined when "kernel/yosys.h" is included and USING_YOSYS_NAMESPACE is used.
+
+  1. Yosys Container Classes
+
+Yosys uses dict<K, T> and pool<T> as main container classes. dict<K, T> is
+essentially a replacement for std::unordered_map<K, T> and pool<T> is a
+replacement for std::unordered_set<T>. The main characteristics are:
+
+	- dict<K, T> and pool<T> are about 2x faster than the std containers
+
+	- references to elements in a dict<K, T> or pool<T> are invalidated by
+	  insert and remove operations (similar to std::vector<T> on push_back()).
+
+	- some iterators are invalidated by erase(). specifically, iterators
+	  that have not passed the erased element yet are invalidated. (erase()
+	  itself returns valid iterator to the next element.)
+
+	- no iterators are invalidated by insert(). elements are inserted at
+	  begin(). i.e. only a new iterator that starts at begin() will see the
+	  inserted elements.
+
+	- the method .count(key, iterator) is like .count(key) but only
+	  considers elements that can be reached via the iterator.
+
+	- iterators can be compared. it1 < it2 means that the position of t2
+	  can be reached via t1 but not vice versa.
+
+	- the method .sort() can be used to sort the elements in the container
+	  the container stays sorted until elements are added or removed.
+
+	- dict<K, T> and pool<T> will have the same order of iteration across
+	  all compilers, standard libraries and architectures.
+
+In addition to dict<K, T> and pool<T> there is also an idict<K> that
+creates a bijective map from K to the integers. For example:
+
+	idict<string, 42> si;
+	log("%d\n", si("hello"));      // will print 42
+	log("%d\n", si("world"));      // will print 43
+	log("%d\n", si.at("world"));   // will print 43
+	log("%d\n", si.at("dummy"));   // will throw exception
+	log("%s\n", si[42].c_str()));  // will print hello
+	log("%s\n", si[43].c_str()));  // will print world
+	log("%s\n", si[44].c_str()));  // will throw exception
+
+It is not possible to remove elements from an idict.
+
+Finally mfp<K> implements a merge-find set data structure (aka. disjoint-set or
+union-find) over the type K ("mfp" = merge-find-promote).
+
+  2. Standard STL data types
+
+In Yosys we use std::vector<T> and std::string whenever applicable. When
+dict<K, T> and pool<T> are not suitable then std::map<K, T> and std::set<T>
+are used instead.
+
+The types std::vector<T> and std::string are also available as vector<T>
+and string in the Yosys namespace.
+
+  3. RTLIL objects
+
+The current design (essentially a collection of modules, each defined by a
+netlist) is stored in memory using RTLIL object (declared in kernel/rtlil.h,
+automatically included by kernel/yosys.h). You should glance over at least
+the declarations for the following types in kernel/rtlil.h:
+
+	RTLIL::IdString
+		This is a handle for an identifier (e.g. cell or wire name).
+		It feels a lot like a std::string, but is only a single int
+		in size. (The actual string is stored in a global lookup
+		table.)
+
+	RTLIL::SigBit
+		A single signal bit. I.e. either a constant state (0, 1,
+		x, z) or a single bit from a wire.
+
+	RTLIL::SigSpec
+		Essentially a vector of SigBits.
+
+	RTLIL::Wire
+	RTLIL::Cell
+		The building blocks of the netlist in a module.
+
+	RTLIL::Module
+	RTLIL::Design
+		The module is a container with connected cells and wires
+		in it. The design is a container with modules in it.
+
+All this types are also available without the RTLIL:: prefix in the Yosys
+namespace.
+
+  4. SigMap and other Helper Classes
+
+There are a couple of additional helper classes that are in wide use
+in Yosys. Most importantly there is SigMap (declared in kernel/sigtools.h).
+
+When a design has many wires in it that are connected to each other, then a
+single signal bit can have multiple valid names. The SigMap object can be used
+to map SigSpecs or SigBits to unique SigSpecs and SigBits that consistently
+only use one wire from such a group of connected wires. For example:
+
+	SigBit a = module->addWire(NEW_ID);
+	SigBit b = module->addWire(NEW_ID);
+	module->connect(a, b);
+
+	log("%d\n", a == b); // will print 0
+
+	SigMap sigmap(module);
+	log("%d\n", sigmap(a) == sigmap(b)); // will print 1
+
+
+Using the RTLIL Netlist Format
+------------------------------
+
+In the RTLIL netlist format the cell ports contain SigSpecs that point to the
+Wires. There are no references in the other direction. This has two direct
+consequences:
+
+(1) It is very easy to go from cells to wires but hard to go in the other way.
+
+(2) There is no danger in removing cells from the netlists, but removing wires
+can break the netlist format when there are still references to the wire
+somewhere in the netlist.
+
+The solution to (1) is easy: Create custom indexes that allow you to make fast
+lookups for the wire-to-cell direction. You can either use existing generic
+index structures to do that (such as the ModIndex class) or write your own
+index. For many application it is simplest to construct a custom index. For
+example:
+
+	SigMap sigmap(module);
+	dict<SigBit, Cell*> sigbit_to_driver_index;
+
+	for (auto cell : module->cells())
+		for (auto &conn : cell->connections())
+			if (cell->output(conn.first))
+				for (auto bit : sigmap(conn.second))
+					sigbit_to_driver_index[bit] = cell;
+
+Regarding (2): There is a general theme in Yosys that you don't remove wires
+from the design. You can rename them, unconnect them, but you do not actually remove
+the Wire object from the module. Instead you let the "clean" command take care
+of the dangling wires. On the other hand it is safe to remove cells (as long as
+you make sure this does not invalidate a custom index you are using in your code).
+
+
+Example Code
+------------
+
+The following yosys commands are a good starting point if you are looking for examples
+of how to use the Yosys API:
+
+	manual/CHAPTER_Prog/stubnets.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
+------------------------------
+
+For historical reasons not all parts of Yosys adhere to the current coding
+style. When adding code to existing parts of the system, adhere to this guide
+for the new code instead of trying to mimic the style of the surrounding code.
\ No newline at end of file
diff --git a/guidelines/UnitTests b/guidelines/UnitTests
new file mode 100644
index 000000000..d42a63ce5
--- /dev/null
+++ b/guidelines/UnitTests
@@ -0,0 +1,69 @@
+How to add unit test
+====================
+
+Unit test brings some advantages, briefly, we can list some of them (reference
+[1](https://en.wikipedia.org/wiki/Unit_testing)):
+
+* Tests reduce bugs in new features;
+* Tests reduce bugs in existing features;
+* Tests are good documentation;
+* Tests reduce the cost of change;
+* Tests allow refactoring;
+
+With those advantages in mind, it was required to choose a framework which fits
+well with C/C++ code.  Hence, it was chosen (google test)
+[https://github.com/google/googletest], because it is largely used and it is
+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 and pthread
+* Clone google test project from: https://github.com/google/googletest and
+  enter in the project directory
+* Inside project directory, type:
+
+```
+cmake -DBUILD_SHARED_LIBS=ON .
+make
+```
+
+* After compilation, copy all "*.so" inside directory "googlemock" and
+  "googlemock/gtest" to "/usr/lib/"
+* Done! Now you can compile your tests.
+
+If you have any problem, go to the official repository to find help.
+
+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:
+
+* Go to directory "yosys/test/unit/"
+* In this directory you can find something similar Yosys's directory structure.
+  To create your unit test file you have to follow this pattern:
+  fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the
+  unit test for kernel/celledges.cc, you will need to create a file like this:
+  tests/unit/kernel/celledgesTest.cc;
+* Implement your unit test
+
+Run unit test
+-------------
+
+To compile and run all unit tests, just go to yosys root directory and type:
+```
+make unit-test
+```
+
+If you want to remove all unit test files, type:
+```
+make clean-unit-test
+```
diff --git a/guidelines/Windows b/guidelines/Windows
new file mode 100644
index 000000000..3bd86f3ec
--- /dev/null
+++ b/guidelines/Windows
@@ -0,0 +1,60 @@
+Creating the Visual Studio Template Project
+===========================================
+
+1. Create an empty Visual C++ Win32 Console App project
+
+	Microsoft Visual Studio Express 2013 for Windows Desktop
+	Open New Project Wizard (File -> New Project..)
+
+	Project Name: YosysVS
+	Solution Name: YosysVS
+	[X] Create directory for solution
+	[ ] Add to source control
+
+	[X] Console applications
+	[X] Empty Project
+	[ ] SDL checks
+
+2. Open YosysVS Project Properties
+
+	Select Configuration: All Configurations
+
+	C/C++ -> General -> Additional Include Directories
+		Add: ..\yosys
+
+	C/C++ -> Preprocessor -> Preprocessor Definitions
+		Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
+
+3. Resulting file system tree:
+
+	YosysVS/
+	YosysVS/YosysVS
+	YosysVS/YosysVS/YosysVS.vcxproj
+	YosysVS/YosysVS/YosysVS.vcxproj.filters
+	YosysVS/YosysVS.sdf
+	YosysVS/YosysVS.sln
+	YosysVS/YosysVS.v12.suo
+
+4. Zip YosysVS as YosysVS-Tpl-v1.zip
+
+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
\ No newline at end of file
diff --git a/kernel/yosys.h b/kernel/yosys.h
index 43aecdbc8..e93d09cd4 100644
--- a/kernel/yosys.h
+++ b/kernel/yosys.h
@@ -33,7 +33,7 @@
 // This header is very boring. It just defines some general things that
 // belong nowhere else and includes the interesting headers.
 //
-// Find more information in the "CodingReadme" file.
+// Find more information in the "guidelines/GettingStarted" file.
 
 
 #ifndef YOSYS_H
diff --git a/manual/CHAPTER_Prog.tex b/manual/CHAPTER_Prog.tex
index 3cbc95a19..49432f73b 100644
--- a/manual/CHAPTER_Prog.tex
+++ b/manual/CHAPTER_Prog.tex
@@ -5,13 +5,15 @@
 This chapter contains some bits and pieces of information about programming
 yosys extensions. Also consult the section on programming in the ``Yosys
 Presentation'' (can be downloaded from the Yosys website as PDF) and don't
-be afraid to ask questions on the Yosys Subreddit.
+be afraid to ask questions on the YosysHQ Slack.
 
-\section{The ``CodingReadme'' File}
+\section{Guidelines}
 
-The following is an excerpt of the {\tt CodingReadme} file from the Yosys source tree.
+The {\tt guidelines} directory contains notes on various aspects of Yosys development. The files {\tt GettingStarted} and {\tt CodingStyle} may be of particular interest, and are reproduced here.
 
-\lstinputlisting[title=CodingReadme,rangeprefix=--,rangesuffix=--,includerangemarker=false,linerange=snip-snap,numbers=left,frame=single]{../CodingReadme}
+\lstinputlisting[title=GettingStarted,numbers=left,frame=single]{../guidelines/GettingStarted}
+
+\lstinputlisting[title=CodingStyle,numbers=left,frame=single]{../guidelines/CodingStyle}
 
 \section{The ``stubsnets'' Example Module}
 
@@ -23,4 +25,3 @@ The following is the complete code of the ``stubsnets'' example module. It is in
 \lstinputlisting[title=Makefile,numbers=left,frame=single,language=make]{CHAPTER_Prog/Makefile}
 
 \lstinputlisting[title=test.v,numbers=left,frame=single,language=Verilog]{CHAPTER_Prog/test.v}
-
-- 
cgit v1.2.3