(Daniel van der Schuur, 17 Oct. 2018)

Summary
=======
This directory contains vertically grouped versions of the horizontal RadioHDL
HDL libraries, stored on an external OpenCores repository. It cannot harm the
current horizontal libraries, yet it syncs our vertical RadioHDL libs with
the vertical 'cores':

$RADIOHDL/libraries : untouched
$RADIOHDL/cores     : Cores from Opencores repo = modified copies of 
                      $RADIOHDL/libraries source files.

checklist.txt
=============
Contains a checklist we will look at before uploading a core onto OpenCores.
Also contains a more general to-do list.

Introduction
============
This 'cores' directory contains VHDL libraries from the RadioHDL repository, but
organized differently:
- The RadioHDL repository has the HDL files ordered in horizontal libraries,
  grouped together based on hierarchical layer. E.g. all technology-specific 
  HDL files are in the 'technology'-library, and all 'common' HDL files are
  grouped together in one very large library as well.
- This cores repository contains the same (though slightly modifed) HDL files,
  but grouped together vertically. For example, the dp_mux and dp_demux belong
  to the very large horizontal 'dp'-library, but here they could belong to the 
  'dp_mux' library.

The original horizontal organization is however still maintained as directory
structure; e.g. all vertical 'dp' cores are in the 'dp' directory.

copy_source_files.py [library]
==============================
This script copies the source files from the horizontal RadioHDL repository,
with the purpose of:
1) Keeping this 'cores' library in sync with our 'official' RadioHDL library,
   without risk of doing damage to it.
2) Provide option to migrate to this vertical for by calling 'svn move'
If no argument is passed, it will copy/overwrite ALL source files listed in the
hdllib.cfg files. 
Pass a library name to copy only the source files for a specific library (e.g.
common_pkg).

edit_source_files.py [library]
==============================
This script edits the copied files such that:
1) the included horizontal libraries at the top are replaced by vertical ones;
2) the horizontal libraries named in the instantiations are replaced with
   vertical ones.
If no argument is passed, it will edit/overwrite ALL source files listed in the
hdllib.cfg files. 
Pass a library name to edit only the source files for a specific library (e.g.
common_pkg).

How this is organized in SVN
============================
The actual 'core' directories (such as base/common/common_pkg) don't exist on
our own RADIOHDL SVN server. They are pulled in from the OpenCores repository.
An example command to set this up in SVN is shown below (svn propset).

How to add a new 'core'
=======================
This assumes that your 'new' core is just a vertical representation of existing
source files. If your project is entirely new, steps 6 and 7 have no effect an
can be omitted.
1) Go to OpenCores.org, log in, create new project with name 'my_project'.
2a)After it is approved, include it in our RADIOHDL repository by defining
   an external repo by running the following command in the desired parent
   directory:

   $ svn propset svn:externals -F svn_propset_file .

   For this project, add the following line to svn_propset_file:

   my_project https://opencores.org/ocsvn/my_project/my_project/trunk/

   The svn_propset_files are in SVN in their respective folders.
2b)Commit this SVN folder setting
2c)SVN update; you will now get the project folder from the OpenCore repo.
3) Add an hdllib.cfg file to the project dir, edit source files list.
4) Run: $ python copy_source_files.py my_project
5) Modify edit_source_files.py: add entries to REPLACE_LIST using existing
   entries as examples.
6) Run: $ python edit_source_files my_project
7) Try the project in simulation, if it works: SVN commit to to OpenCores.