From 8d719604efff5854a42bf4041cb77136cd7b402e Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Fri, 8 May 2020 17:51:41 -0700 Subject: [PATCH] docs: Generate README.rst to work around GitHub not rendering `.. include::` in rst files. This work might look like extensive for just fixing a small issue like the include rendering, but it will all be heavily reused by the skywater-pdk scripts that will be released soon. This commit; - Adds Makefile for creating a self contained conda environment under `env/conda` - Installs required Python dependencies into the environment (which is currently just the `rst_include` tool). - Has a Makefile to generate `README.rst` from `README.src.rst` - Has Travis CI run on repository and check that the `README.rst` file has been rebuilt and committed if any of the dependencies have change. Signed-off-by: Tim 'mithro' Ansell --- .github/travis/common.sh | 48 ++++++++++++ .github/travis/git-check.sh | 44 +++++++++++ .gitignore | 138 +++++++++++++++++++++++++++++++++++ .travis.yml | 30 ++++++++ Makefile | 22 ++++++ README.rst => README.src.rst | 12 +-- docs/status.rst | 2 +- docs/versioning.rst | 4 +- environment.yml | 7 ++ requirements.txt | 3 + scripts/make/conda.mk | 88 ++++++++++++++++++++++ scripts/make/git.mk | 20 +++++ 12 files changed, 405 insertions(+), 13 deletions(-) create mode 100644 .github/travis/common.sh create mode 100755 .github/travis/git-check.sh create mode 100644 .gitignore create mode 100644 .travis.yml create mode 100644 Makefile rename README.rst => README.src.rst (85%) create mode 100644 environment.yml create mode 100644 requirements.txt create mode 100644 scripts/make/conda.mk create mode 100644 scripts/make/git.mk diff --git a/.github/travis/common.sh b/.github/travis/common.sh new file mode 100644 index 0000000..52bc812 --- /dev/null +++ b/.github/travis/common.sh @@ -0,0 +1,48 @@ +#!/usr/env false +# +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +# Some colors, use it like following; +# echo -e "Hello ${YELLOW}yellow${NC}" +GRAY=' \033[0;30m' +RED=' \033[0;31m' +GREEN=' \033[0;32m' +YELLOW=' \033[0;33m' +PURPLE=' \033[0;35m' +NC='\033[0m' # No Color + +SPACER="echo -e ${GRAY} - ${NC}" + +export -f travis_nanoseconds +export -f travis_fold +export -f travis_time_start +export -f travis_time_finish +export -f travis_wait +export -f travis_jigger + +function start_section() { + travis_fold start "$1" + travis_time_start + echo -e "${PURPLE}${1}${NC}: $2${NC}" + echo -e "${GRAY}-------------------------------------------------------------------${NC}" +} + +function end_section() { + echo -e "${GRAY}-------------------------------------------------------------------${NC}" + travis_time_finish + travis_fold end "$1" +} diff --git a/.github/travis/git-check.sh b/.github/travis/git-check.sh new file mode 100755 index 0000000..5791013 --- /dev/null +++ b/.github/travis/git-check.sh @@ -0,0 +1,44 @@ +#!/usr/bin/env bash +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +set -e + +source .github/travis/common.sh + +# Output any changes in the repository +# ------------------------------------------------------------------------ +start_section git-status "Current git status" + +git diff + +$SPACER + +git status + +end_section git-status + +# Check there are not changes in the repository +# ------------------------------------------------------------------------ +start_section git-check "Checking git repository isn't dirty" + +( + . "$(git --exec-path)/git-sh-setup" + + require_clean_work_tree "continue" "Please include the changes in your commits." +) + +end_section git-check diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a81c8ee --- /dev/null +++ b/.gitignore @@ -0,0 +1,138 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..ce23f67 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,30 @@ +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +language: minimal + +git: + submodules: false + depth: false + +install: + - git describe + - make env + +script: + - source .github/travis/common.sh + - rm -f README.rst && make README.rst + - .github/travis/git-check.sh diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..0bb8b96 --- /dev/null +++ b/Makefile @@ -0,0 +1,22 @@ +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +include scripts/make/git.mk +include scripts/make/conda.mk + +README.rst: README.src.rst docs/status.rst | $(CONDA_ENV_PYTHON) + @rm -f README.rst + $(IN_CONDA_ENV) rst_include include --source README.src.rst | sed -e's/|TAG_VERSION|/$(TAG_VERSION)/g' > README.rst diff --git a/README.rst b/README.src.rst similarity index 85% rename from README.rst rename to README.src.rst index 70e8e42..43c1059 100644 --- a/README.rst +++ b/README.src.rst @@ -41,7 +41,7 @@ The SkyWater Open Source PDK documentation can be found at `_ to get more detailed information around currently known issues. SKY130 Process Node -=================== +------------------- The SKY130 is a mature 180nm-130nm hybrid technology originally developed internally by Cypress Semiconductor before being spun out into SkyWater Technology and made accessible to general industry. SkyWater and Google’s collaboration is now making this technology accessible to everyone! @@ -58,19 +58,11 @@ The SKY130 Process node technology stack consists of; * HV extended-drain NMOS and PMOS -The `SKY130 Process Node`_ has is a extremely flexible offering, including many normally *optional* features as standard (feature like the local interconnect, SONOS functionality, MiM capacitors and more). This provides the designer with a **wide range** of flexibility in design choices. - -If your needs extend beyond the standard included functionality in the `SKY130 Process Node`_, please see `Contacting SkyWater`_ as they specializes in enabling production volume of process customization include `the addition of specialized materials like Nb, Ge, V2O5, Carbon Nanotubes `_. Google and SkyWater continuing to explore new options to be included in the `SkyWater Open Source PDK`_ and `SKY130 Process Node`_ that enable new innovative solutions to traditional design problems. - - Typical usages of 130nm Process Nodes -------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `130nm process `_ was first commercialized around the 2001-2002 time frame and is now primarily used in the area of research, small microcontroller development, and mixed signal embedded designs such as IoT devices. -A living Google document at has been created to provide **inspiration** from what researchers, commercial entities and other groups have done with similar **sized** process nodes. As there are widely different constraints and possibilities from changes in both the manufacturing process and materials it is important **not** to assumed that the exact results found in the `130nm inspiration document `_ can be identically reproduced on the `SKY130 Process Node`_. - - PDK Contents ============ diff --git a/docs/status.rst b/docs/status.rst index 4139d4c..2668c29 100644 --- a/docs/status.rst +++ b/docs/status.rst @@ -9,7 +9,7 @@ While the SKY130 process node and the PDK from which this open source release wa Google, SkyWater and our partners are currently doing internal validation and test designs, including silicon validation or the released data and plan to publish these results. -The PDK will be tagged with a production version when ready to do production design, see the `"Versioning Information" <>`_ section for a full description of the version numbering scheme. +The PDK will be tagged with a production version when ready to do production design, see the ":ref:`Versioning Information`" section for a full description of the version numbering scheme. To get notified about future new releases of the PDK, and other important news, please sign up on the `skywater-pdk-announce mailing list `_ diff --git a/docs/versioning.rst b/docs/versioning.rst index a252669..294e216 100644 --- a/docs/versioning.rst +++ b/docs/versioning.rst @@ -1,5 +1,5 @@ -Version Numbering ------------------ +Version Number Format +--------------------- Version numbers for both the PDK and the supplied libraries are fully specified by a 3-digit version number followed by a git commit count and a git commit short hash. diff --git a/environment.yml b/environment.yml new file mode 100644 index 0000000..7ef974e --- /dev/null +++ b/environment.yml @@ -0,0 +1,7 @@ +name: skywater-pdk-scripts +dependencies: +- python +- pip +# Packages installed from PyPI +- pip: + - -r file:requirements.txt diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..e4e2ff4 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +# rst_include tool as GitHub doesn't support `.. include::` when rendering +# previews. +rst_include diff --git a/scripts/make/conda.mk b/scripts/make/conda.mk new file mode 100644 index 0000000..68b52a0 --- /dev/null +++ b/scripts/make/conda.mk @@ -0,0 +1,88 @@ +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 + +SHELL := /bin/bash + +UNAME_S := $(shell uname -s) +ifneq (, $(findstring Linux, $(UNAME_S))) + OSFLAG := Linux +endif +ifeq ($(UNAME_S), Darwin) + OSFLAG := MacOSX +endif +ifneq (, $(findstring Cygwin, $(UNAME_S))) + OSFLAG := Linux +endif +ifneq (, $(findstring MINGW, $(UNAME_S))) + OSFLAG := Linux +endif + +TOP_DIR := $(shell git rev-parse --show-toplevel) +ENV_DIR := $(TOP_DIR)/env +REQUIREMENTS_FILE := $(TOP_DIR)/requirements.txt +ENVIRONMENT_FILE := $(TOP_DIR)/environment.yml + +CONDA_DIR := $(ENV_DIR)/conda +DOWNLOADS_DIR := $(ENV_DIR)/downloads +CONDA_PYTHON := $(CONDA_DIR)/bin/python +CONDA_PKGS_DIR := $(DOWNLOADS_DIR)/conda-pkgs +CONDA_PKGS_DEP := $(CONDA_PKGS_DIR)/urls.txt +CONDA_ENV_NAME := skywater-pdk-scripts +CONDA_ENV_PYTHON := $(CONDA_DIR)/envs/$(CONDA_ENV_NAME)/bin/python +IN_CONDA_ENV_BASE := source $(CONDA_DIR)/bin/activate && +IN_CONDA_ENV := $(IN_CONDA_ENV_BASE) conda activate $(CONDA_ENV_NAME) && + +$(ENV_DIR): | $(DOWNLOADS_DIR) + mkdir -p $(END_DIR) + +$(DOWNLOADS_DIR): + mkdir -p $(DOWNLOADS_DIR) + +$(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh: | $(DOWNLOADS_DIR) + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-$(OSFLAG)-x86_64.sh -O $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh + chmod a+x $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh + +$(CONDA_PKGS_DEP): $(CONDA_PYTHON) + $(IN_CONDA_ENV_BASE) conda config --system --add pkgs_dirs $(CONDA_PKGS_DIR) + +$(CONDA_PYTHON): $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh + $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh -p $(CONDA_DIR) -b -f + +$(CONDA_DIR)/envs: $(CONDA_PYTHON) + $(IN_CONDA_ENV_BASE) conda config --system --add envs_dirs $(CONDA_DIR)/envs + +$(CONDA_ENV_PYTHON): $(ENVIRONMENT_FILE) $(REQUIREMENTS_FILE) | $(CONDA_PYTHON) $(CONDA_DIR)/envs $(CONDA_PKGS_DEP) + $(IN_CONDA_ENV_BASE) conda env update --name $(CONDA_ENV_NAME) --file $(ENVIRONMENT_FILE) + +env: $(CONDA_ENV_PYTHON) + $(IN_CONDA_ENV) conda info + +.PHONY: env + +enter: $(CONDA_ENV_PYTHON) + $(IN_CONDA_ENV) bash + +.PHONY: enter + +clean: + rm -rf env/conda + +.PHONY: clean + +dist-clean: + rm -rf conda + +.PHONY: dist-clean diff --git a/scripts/make/git.mk b/scripts/make/git.mk new file mode 100644 index 0000000..a058758 --- /dev/null +++ b/scripts/make/git.mk @@ -0,0 +1,20 @@ +# Copyright 2020 SkyWater PDK Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +FULL_VERSION := $(shell git describe --long) +TAG_VERSION := $(firstword $(subst -, ,$(FULL_VERSION))) + +ifeq (,$(FULL_VERSION)) +$(error "Version value could not be determined. Make sure you fetch the tags.") +endif