Merge pull request #1068 from ygorelik/master

Releasing YDK-0.8.6.3

.gitignore

@@ -8,6 +8,7 @@
 .temp
 .idea*
 .coverage*
+.env
 htmlcov
 coverage.xml
 *.pyc

CHANGES.md

@@ -1,3 +1,23 @@
+### 2022-07-31 version 0.8.6.3
+
+#### New features and enhancements
+  * Added automatic build of environment setup file .env by the installation script
+
+#### Resolved GitHub issues
+  * IndexError on decoding empty string value in JSON payload ([#1061](https://github.com/CiscoDevNet/ydk-gen/issues/1061))
+  * gNMI service installation on Centos 8.2 fails due to C++ compiler error
+([#1062](https://github.com/CiscoDevNet/ydk-gen/issues/1062))
+  * The installation script fails on fresh new CentOS 7 docker container ([#1064](https://github.com/CiscoDevNet/ydk-gen/issues/1064))
+  * ExecutorService fails on non-ietf RPC with Libyang error ([#1067](https://github.com/CiscoDevNet/ydk-gen/issues/1067))
+
+### Resolved non-GitHub issues
+  * Upgraded third party packages Sphinx (1.5.6) and wheel (0.37.1) due to documentation
+generation issues on Mac Big Sur
+  * Fixed installation script for the case, when virtual environment is not used
+
+#### Documentation improvements
+  * Fixed documentation issue [#1066](https://github.com/CiscoDevNet/ydk-gen/issues/1066)
+
 ### 2022-03-31 version 0.8.6.2
 
 #### New features and enhancements

README.md

@@ -111,14 +111,15 @@ To use the docker image, [install docker](https://docs.docker.com/install/) on y
 See the [docker documentation](https://docs.docker.com/engine/reference/run/) for more details.
 
 ```
-docker run -it ydksolutions/ydk-gen
+docker run -it ydksolutions/ydk-gen:0.8.6.3
 ```
 
 # System Requirements
 
 The YDK is currently supported on the following platforms including native installations, virtual machines, and docker images:
  - Linux Ubuntu Xenial (16.04 LTS), Bionic (18.04 LTS), and Focal (20.04 LTS)
- - Linux CentOS/RHEL versions 7 and 8
+ - Linux CentOS versions 7 and Centos Stream 8 (Centos 8.x has been EOL as of December 31 of 2021)
+ - Linux RHEL version 7.x and 8.x 
  - MacOS up to 11.6.2 (Big Sur)
 
 On Windows 10 the Linux virtual machine can run using Windows Subsystem for Linux (WSL);
@@ -134,6 +135,7 @@ All YDK core components are based on C and C++ code. These components compiled u
 Corresponding binaries, libraries, and header files are installed in default locations,
 which are `/usr/local/bin`, `/usr/local/lib`, and `/usr/local/include`.
 The user must have sudo access in order to install YDK core components to these locations.
+Make sure the `sudo` package is installed on your platform prior to the YDK installation procedure.
 
 # Core Installation
 
@@ -142,21 +144,32 @@ The user must have sudo access in order to install YDK core components to these
 For YDK installation it is recommended to use script `install_ydk.sh` from `ydk-gen` git repository.
 The script detects platform OS, installs all the dependencies and builds complete set of YDK components for specified language.
 
+If the script installs any YDK component, it also creates an environment activation file '.env' in the 'ydk-gen'
+directory, which can be used to activate YDK runtime environment identical to the installation environment.
+To activate YDK runtime environment simply run this command once in bash shell:
+
+```
+cd ydk-gen
+source .env
+```
+
 The YDK extensively uses Python scripts for building its components and model API packages (bundles).
 By default the YDK uses Python system installation.
 In order to isolate YDK Python environment from system installation, the script can build Python3 virtual environment.
 If built, the user must manually activate virtual environment when generating model bundles and/or running YDK based application.
 By default the Python virtual environment is installed under `$HOME/venv` directory.
 For different location the PYTHON_VENV environment variable should be set to that location.
 
-Here is simple example of core YDK installation for Python programming language:
+**NOTE.** It is strongly recommended to use Python virtual environment on Centos/RHEL and Mac platforms.
+
+Here is simple example of core YDK installation for Python programming language and Python virtual environment:
 
 ```
 git clone https://github.com/ygorelik/ydk-gen.git
 cd ydk-gen
 export YDKGEN_HOME=`pwd`  # optional
 export PYTHON_VENV=$HOME/ydk_vne  # optional
-./install_ydk.sh --core
+./install_ydk.sh --core --venv
 ```
 
 The script also allows to install individual components like dependencies, core, and service packages
@@ -181,7 +194,7 @@ Environment variables:
 YDKGEN_HOME         specifies location of ydk-gen git repository;
                     if not set, $HOME/ydk-gen is assumed
 PYTHON_VENV         specifies location of python virtual environment;
-                    if not set, /home/ygorelik/venv is assumed
+                    if not set, $HOME/venv is assumed
 GOROOT              specifies installation directory of go software;
                     if not set, /usr/local/go is assumed
 GOPATH              specifies location of go source directory;
@@ -234,8 +247,8 @@ For unsupported platforms it is recommended to follow logic of `ydk-gen/test/dep
 ### Installing core components
 
 ```
-# If created, activate Python virtual environment
-source $PYTHON_VENV/bin/activate
+# If created, activate YDK runtime environment
+source .env
 
 # Generate and install YDK core library
 ./generate.py -is --core --cpp
@@ -263,6 +276,9 @@ cd ydk-gen
 
 ### Runtime environment
 
+When YDK is installed using 'install_ydk.sh' script, the runtime environment is set by running 'source .env' in bash shell.
+The below information is applicable only when YDK is installed manually, which is not recommended.
+
 There is an open issue with gRPC on Centos/RHEL, which requires an extra step before running any YDK gNMI application.
 See this issue on [GRPC GitHub](https://github.com/grpc/grpc/issues/10942#issuecomment-312565041) for details.
 As a workaround, the YDK based application runtime environment must include setting of `LD_LIBRARY_PATH` variable:
@@ -278,6 +294,7 @@ All the YDK components/packages can be generated by using Python script `generat
 
 ```
 cd ydk-gen
+source .env
 ./generate.py --help
 usage: generate.py [-h] [-l] [--core] [--service SERVICE] [--bundle BUNDLE]
                    [--adhoc-bundle-name ADHOC_BUNDLE_NAME]
@@ -402,10 +419,11 @@ Only directory examples are shown in this example.
 ## Generate and install model bundle
 
 Generate model bundle using a bundle profile and install it.
+YDK runtime environment must be activated prior to these procedures.
 
 ### For Python
 
-Python virtual environment must be activated prior to these procedures
+If applicable, the Python virtual environment must be activated prior to these procedures
 
 ```
 ./generate.py --python --bundle profiles/bundles/<name-of-profile>.json -i
@@ -415,15 +433,14 @@ Check Python packages installed:
 
 ```
 pip list | grep ydk
-ydk (0.8.6)
+ydk (0.8.6.3)
 ydk-models-<name-of-bundle> (0.5.1)
 ...
 ```
 
 ### For Go
 
 ```
-export $GOPATH=/your-go-path-installation-directory  # default location is ~/go
 ./generate.py --go --bundle profiles/bundles/<name-of-profile>.json -i
 ```
 
@@ -557,88 +574,45 @@ cd /path/to/yang/models
 pyang *.yang
 ```
 
-# Running Unit Tests
-
-## Python
+## Running Unit Tests
 
-#### Install the core and bundle packages
+The repository includes complete set of unit tests for all supported languages. To invoke the test for specific language,
+simply get to 'ydk-gen' directory, activate runtime environment, if it was not done previously, and run language specific script.
+The script will install core and bundle packages and then perform the unit tests.
 
-After installing C++ core packages and activating Python virtual environment:
-
-1. Install bundle package
+**C++**
 
     ```
     cd ydk-gen
-    ./generate.py -i --core
-    ./generate.py -i --bundle profiles/test/ydktest-cpp.json
+    source .env  # if previously not run
+    ./test/run_cpp_tests
     ```
 
-2. Start confd
-
-    ```
-    source $HOME/confd/confdrc
-    cd ydk-gen/sdk/cpp/core/tests/confd/ydktest
-    make all
-    make start
-    ```
-
-3. Run unit tests
-
-    ```
-    cd ydk-gen/sdk/python
-    python test/test_sanity_types.py
-    python test/test_sanity_levels.py
-    python test/test_sanity_filters.py
-    ```
-
-## C++
-
-1. Install the core and bundle packages
+**Python**
 
     ```
     cd ydk-gen
-    ./generate.py -is --core --cpp
-    ./generate.py -is --bundle profiles/test/ydktest-cpp.json --cpp
-    ```
-
-2. Run the core unit tests
-
-    ```
-    cd ydk-gen/gen-api/cpp/ydk/build
-    ./test/ydk_core_test
+    source .env  # if previously not run
+    ./test/run_py_tests
     ```
 
-3. Start confd
+**Go**
 
     ```
-    source $HOME/confd/confdrc
-    cd ydk-gen/sdk/cpp/core/tests/confd/ydktest
-    make all
-    make start
-    ```
-
-4. Build and run bundle unit tests
-
-    ```
-    cd ydk-gen/sdk/cpp/tests
-    mkdir -p build && cd build
-    cmake .. && make
-    ./ydk_bundle_test
+    cd ydk-gen
+    source .env  # if previously not run
+    ./test/run_go_tests
     ```
 
-## Go
-
-Please refer [here](https://github.com/ygorelik/ydk-gen/blob/master/sdk/go/core/README.md).
-
 # Documentation and Support
 
-- Read the online [YDK documentation](http://ydk.cisco.com/py/docs) (release 0.8.3) for details on how to use the YDK and API for specific models
+<!--- - Read the online [YDK documentation](http://ydk.cisco.com/py/docs) (release 0.8.3) for details on how to use the YDK and API for specific models -->
 - Check [GitHub Pages](https://ygorelik.github.io/ydk-gen/) for the latest YDK release documentation
 - Find hundreds of sample apps in the [ydk-py-samples](https://github.com/CiscoDevNet/ydk-py-samples) repository
 - Join the [YDK community](https://communities.cisco.com/community/developer/ydk) to connect with YDK users and developers
 
 # Release Notes
 
-The current YDK release version is 0.8.6.
+The current YDK release version is 0.8.6.3.
 
 YDK-Gen is licensed under the Apache 2.0 License.