From 7790d4aa00bc3e22c5f55b68ac2e258db9b6000d Mon Sep 17 00:00:00 2001
From: Blake Harnden <32446120+bharnden@users.noreply.github.com>
Date: Fri, 11 Sep 2020 16:26:13 -0700
Subject: [PATCH] docs: update install.md to denote the option for installing
 locally and reference that as a possibility in other instructions

---
 docs/install.md | 72 ++++++++++++++++++++++++++++++++++++-------------
 install.sh      |  2 +-
 tasks.py        |  7 +++--
 3 files changed, 59 insertions(+), 22 deletions(-)

diff --git a/docs/install.md b/docs/install.md
index 7b5014c4..02193994 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -74,11 +74,14 @@ sudo apt remove core
 
 ## Automated Installation
 
-The automated install will install the various tools needed to help automate
-the CORE installation (python3, pip, pipx, invoke, poetry). The script will
-also automatically clone, build, and install the latest version of OSPF MDR.
-Finally it will install CORE scripts and a systemd service, which have
-been modified to use the installed poetry created virtual environment.
+The automated install will install do the following:
+* install base tools needed for installation
+  * python3, pip, pipx, invoke, poetry
+* installs system dependencies for building core
+* installs latest version of [OPSF MDR](https://github.com/USNavalResearchLaboratory/ospf-mdr)
+* installs core into poetry managed virtual environment or locally, if flag is passed
+* installs scripts pointing to python interpreter being used
+* installs systemd service, disabled by default
 
 After installation has completed you should be able to run the various
 CORE scripts for running core.
@@ -92,10 +95,11 @@ git clone https://github.com/coreemu/core.git
 cd core
 
 # run install script
-# script usage: install.sh [-d] [-v]
+# script usage: install.sh [-v] [-d] [-l] [-p <prefix>]
 #
 # -v enable verbose install
 # -d enable developer install
+# -l enable local install, not compatible with developer install
 # -p install prefix, defaults to /usr/local
 ./install.sh
 ```
@@ -117,16 +121,17 @@ After the installation complete it will have installed the following scripts.
 
 | Name | Description |
 |---|---|
+| core-cleanup | tool to help removed lingering core created containers, bridges, directories |
+| core-cli | tool to query, open xml files, and send commands using gRPC |
 | core-daemon | runs the backed core server providing TLV and gRPC APIs |
 | core-gui | runs the legacy tcl/tk based GUI |
-| core-pygui | runs the new python/tk based GUI |
-| core-cleanup | tool to help removed lingering core created containers, bridges, directories |
 | core-imn-to-xml | tool to help automate converting a .imn file to .xml format |
+| core-manage | tool to add, remove, or check for services, models, and node types |
+| core-pygui | runs the new python/tk based GUI |
+| core-python | provides a convenience for running the core python virtual environment |
 | core-route-monitor | tool to help monitor traffic across nodes and feed that to SDT |
 | core-service-update | tool to update automate modifying a legacy service to match current naming |
 | coresendmsg | tool to send TLV API commands from command line |
-| core-cli | tool to query, open xml files, and send commands using gRPC |
-| core-manage | tool to add, remove, or check for services, models, and node types |
 
 ## Running User Scripts
 
@@ -142,28 +147,57 @@ environment interpreter or to run a script within it.
 core-python <script>
 ```
 
-## Manually Install EMANE
+If CORE was installed locally, then you can run scripts using the default python3
+interpreter.
 
-EMANE can be installed from deb or RPM packages or from source. See the
-[EMANE GitHub](https://github.com/adjacentlink/emane) for full details.
+```shell
+python3 <script>
+```
 
-There is an invoke task to help with installing EMANE, but has issues,
-which attempts to build EMANE from source, but has issue on systems with
- older protobuf-compilers.
+## Installing EMANE
+
+> **NOTE:** installng emane for the virtual environment is known to work for 1.21+
+> **NOTE:** automated install currently targets 1.25
+
+There is an invoke task to help with installing EMANE, which attempts to
+build EMANE from source, but has issue on systems with older protobuf-compilers.
 
 ```shell
 cd <CORE_REPO>
+
+# install to virtual environment
 inv install-emane
+
+# install locally to system python3
+inv install-emane -l
 ```
 
-Alternatively, you can
+Alternatively EMANE can be installed from deb or RPM packages or from source. See the
+[EMANE GitHub](https://github.com/adjacentlink/emane) for full details.
+With the caveat that the python bindings need to be installed into CORE's
+virtualenv, unless installed locally.
+
+### Installing EMANE Python Bindings for Virtual Environment
+
+If you need to just install the EMANE python bindings to the CORE virtual
+environment, since you are installing EMANE itself from pre-built packages.
+You can run the following
+
+Leveraging the following wiki:
 [build EMANE](https://github.com/adjacentlink/emane/wiki/Build)
-from source and install the python
-bindings into the core virtual environment.
 
 The following would install the EMANE python bindings after being
 successfully built.
 ```shell
+# clone and build emane python bindings
+git clone https://github.com/adjacentlink/emane.git
+cd emane
+./autogen.sh
+PYTHON=python3 ./configure --prefix=/usr
+cd src/python
+make
+
+# install to core virtual environment
 cd <CORE_REPO>/daemon
 poetry run pip install <EMANE_REPO>/src/python
 ```
diff --git a/install.sh b/install.sh
index 59584afa..3d100a62 100755
--- a/install.sh
+++ b/install.sh
@@ -30,7 +30,7 @@ while getopts "dvlp:" opt; do
     prefix="-p ${OPTARG}"
     ;;
   \?)
-    echo "script usage: $(basename $0) [-d] [-v]" >&2
+    echo "script usage: $(basename $0) [-v] [-d] [-l] [-p <prefix>]" >&2
     echo "" >&2
     echo "-v enable verbose install" >&2
     echo "-d enable developer install" >&2
diff --git a/tasks.py b/tasks.py
index 845e0f16..4b858465 100644
--- a/tasks.py
+++ b/tasks.py
@@ -449,11 +449,14 @@ def uninstall(c, dev=False, verbose=False, prefix=DEFAULT_PREFIX):
     help={
         "dev": "reinstall development mode",
         "verbose": "enable verbose",
+        "local": "determines if core will install to local system, default is False",
         "prefix": f"prefix where scripts are installed, default is {DEFAULT_PREFIX}",
         "branch": "branch to install latest code from, default is current branch"
     },
 )
-def reinstall(c, dev=False, verbose=False, prefix=DEFAULT_PREFIX, branch=None):
+def reinstall(
+    c, dev=False, verbose=False, local=False, prefix=DEFAULT_PREFIX, branch=None
+):
     """
     run the uninstall task, get latest from specified branch, and run install task
     """
@@ -469,7 +472,7 @@ def reinstall(c, dev=False, verbose=False, prefix=DEFAULT_PREFIX, branch=None):
         c.run("git pull", hide=hide)
         if not Path("tasks.py").exists():
             raise FileNotFoundError(f"missing tasks.py on branch: {branch}")
-    install(c, dev, verbose, prefix)
+    install(c, dev, verbose, local, prefix)
 
 
 @task