Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated development guide with details #268

Merged
merged 6 commits into from
Aug 23, 2019
Merged

Updated development guide with details #268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9541a4f
Updated developement guide with details
Aug 15, 2019
182f4d0
Update development_guide.md
Aug 16, 2019
ed1f502
Python setting files are created for vscode
Aug 16, 2019
10d1ee5
Resolved PR comments
Aug 22, 2019
57161e3
Update development_guide.md
Aug 22, 2019
37145b3
Create .env
Aug 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .env
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
MSSQL_CLI_SERVER=
MSSQL_CLI_DATABASE=
MSSQL_CLI_USER=
MSSQL_CLI_PASSWORD=
25 changes: 25 additions & 0 deletions .vscode/launch.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"version": "0.2.0",
"configurations": [
geleems marked this conversation as resolved.
Show resolved Hide resolved
{
"name": "Python: Launch mssql-cli (integrated)",
"type": "python",
"request": "launch",
"program": "${workspaceRoot}/mssqlcli/main.py",
"env": {
"PYTHONPATH":"${workspaceRoot};${env:PYTHONPATH}"
},
"console": "integratedTerminal",
},
{
"name": "Python: Launch mssql-cli (external)",
"type": "python",
"request": "launch",
"program": "${workspaceRoot}/mssqlcli/main.py",
"env": {
"PYTHONPATH":"${workspaceRoot};${env:PYTHONPATH}"
},
"console": "externalTerminal",
}
]
}
12 changes: 12 additions & 0 deletions .vscode/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"python.pythonPath": "${workspaceRoot}/env/Scripts/python.exe",
"python.linting.pylintEnabled": true,
"python.testing.nosetestsEnabled": true,
"python.testing.nosetestArgs": [
"tests",
"mssqlcli/jsonrpc/tests",
"mssqlcli/jsonrpc/contracts/tests"
],
"python.testing.pytestEnabled": false,
"python.testing.unittestEnabled": false
}
325 changes: 214 additions & 111 deletions doc/development_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@

Development Guide
=================

Expand All @@ -12,134 +13,236 @@ a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow th
provided by the bot. You will only need to do this once across all repos using our CLA.

## Table of Contents
1. [Preparing your machine](#Preparing_machine)
1. [Environment Setup](#Environment_Setup)
2. [Configuring IDE](#Configure_IDE)
3. [Running Tests](#Running_Tests)
5. [Running mssql-cli](#Run_mssql-cli)
1. [Install Python / Clone Source Code](#Install_Python_Clone_Source_Code)
2. [Create Virtual Environment](#Create_Virtual_Environment)
3. [Build mssql-cli](#Build_mssql_cli)
4. [Run mssql-cli From Source Code](#Run_mssql-cli_From_Source_Code)
5. [Run Unit Tests / Integration Tests](#Run_Unit_Tests_Integration_Tests)
2. [IDE Setup](#IDE_Setup)
1. [Install Visual Studio Code](#Install_Visual_Studio_Code)
2. [Configure Python Settings in Visual Studio Code](#Configure_Python_Settings_in_Visual_Studio_Code)
3. [How To Run mssql-cli With Debugger](#How_To_Run_mssql_cli_With_Debugger)
4. [How To Run Unit Tests With / Without Debugger](#How_To_Run_Unit_Tests_With_Without_Debugger)


# <a name="Environment_Setup"></a>Environment Setup

mssql-cli sources are located on GitHub (https://github.com/dbcli/mssql-cli). In order to contribute to the project, you are expected to:
- Have a GitHub account. For Microsoft contributors, follow the guidelines on https://opensourcehub.microsoft.com/ to create, configure and link your account
- Fork the https://github.com/dbcli/mssql-cli repository into your private GitHub account
- Create pull requests against the https://github.com/dbcli/mssql-cli repository to get your code changes merged into the project repository.

## <a name="Preparing_Machine"></a>1. Preparing your machine
1. Install latest Python from http://python.org. Please note that the version of Python that comes preinstalled on OSX is 2.7. It is recommended to install both Python 2.7 and Python3.6 to ensure backwards compatibility for testing.
## <a name="Install_Python_Clone_Source_Code"></a>1. Install Python / Clone Source Code
1. Install latest Python from http://python.org. Please note that the version of Python that comes preinstalled on OSX is 2.7. It is recommended to install both Python 2.7 and Python3.7 to ensure backwards compatibility for testing.
#### Windows
- The latest Python installation package can be downloaded from [here](https://www.python.org/downloads/).
- During installation, select the 'Add Python to PATH' option. Python must be in the PATH environment variable.

2. Clone the repo from [https://github.com/dbcli/mssql-cli](https://github.com/dbcli/mssql-cli)

## <a name="Environment_Setup"></a>2. Environment Setup
## <a name="Create_Virtual_Environment"></a>2. Create Virtual Environment
When developing on a Python project, it is recommended to do so in a virtual environment. A virtual environment is a sandbox that maintains a copy of all libraries necessary to run python in a isolated environment without interfering with the system or global python. For more information on virtual environments, go to [Virtual Environment Info](virtual_environment_info.md).

If not developing in a virtual environment, please proceed to [Development Setup](#Development)
### Virtual Environment
1. Create a virtual environment in a subdirectory of your `<clone_root>`, using `<clone_root>/env` as a example:

##### Windows
```
python -m venv <clone_root>\env
```
##### MacOS/Linux (bash)
```
python –m venv <clone_root>/env
```
2. Activate the env virtual environment by running:

##### Windows
```
<clone_root>\env\scripts\activate.bat
```
##### MacOS/Linux (bash)
```
. <clone_root>/env/bin/activate
```
3. To deactivate the virtual environment:

##### Windows
```
<clone_root>\env\scripts\deactivate.bat
```
##### MacOS/Linux (bash)
```
deactivate
```
### <a name="Development"></a>Development Setup
General development steps that apply to both a virtual environment or a global environment. If working in a virtual environment, do ensure the virtual environment is activated.
1. Add `<clone_root>` to your PYTHONPATH environment variable:

##### Windows
```
set PYTHONPATH=<clone_root>;%PYTHONPATH%
```
##### MacOS/Linux (bash)
```
export PYTHONPATH=<clone_root>:${PYTHONPATH}
```
2. Install the dependencies:
```
python <clone_root>/dev_setup.py
```
## <a name="Configure_IDE"></a>3. Configuring your IDE

#### Visual Studio Code (Any platform)

1. Install VS Code
If not developing in a virtual environment, please proceed to [Install All Dependencies](#Install_All_Dependencies)

### 1. Create Virtual Environment
Create a virtual environment in a subdirectory of your `<workspaceRoot>` (`<workspaceRoot>/env`, for example). Open command prompt or bash.

##### Windows (Python3.x)
```
set PYLOC=<python3_location>
set PATH=%PYLOC%\Scripts;%PYLOC%;%PATH%
python -m venv <workspaceRoot>\env
```
##### Windows (Python2.x)
```
set PYLOC=<python2_location>
set PATH=%PYLOC%\Scripts;%PYLOC%;%PATH%
python -m pip install --upgrade pip
python -m pip install --upgrade virtualenv
python -m virtualenv <workspaceRoot>\env
```
##### MacOS (Python3.x)
```
python3 -m venv <workspaceRoot>/env
```
##### MacOS (Python2.x)
```
python -m venv <workspaceRoot>/env
```
##### Linux (Python3.x) -- Ubuntu for example
```
sudo apt-get update
sudo apt-get install python3-pip
sudo apt-get install python3-venv
python3 -m venv <workspaceRoot>/env
```
##### Linux (Python2.x) -- Ubuntu for example
```
sudo apt-get update
sudo apt-get install python-pip
python -m pip install --upgrade pip
python -m pip install virtualenv
python -m virtualenv <workspaceRoot>/env
```

### 2. Activate Virtual Environment
##### Windows
```
<workspaceRoot>\env\scripts\activate.bat
```
##### MacOS/Linux
```
. <workspaceRoot>/env/bin/activate
```

### (To deactivate the Virtual Environment)
##### Windows/MacOS/Linux
```
deactivate
```

## <a name="Build_mssql_cli"></a>3. Build mssql-cli
General development steps that apply to both a virtual environment or a global environment.
*If working in a virtual environment, do ensure the virtual environment is activated as the first command line of each following script.*

##### Windows
```
<workspaceRoot>\env\scripts\activate.bat

cd <workspaceRoot>
python -m pip install --upgrade pip
python build.py build
```
##### MacOS/Linux (Python3.x)
```
. <workspaceRoot>/env/bin/activate

cd <workspaceRoot>
python3 -m pip install --upgrade pip
python3 build.py build
```
##### MacOS/Linux (Python2.x)
```
. <workspaceRoot>/env/bin/activate

cd <workspaceRoot>
python -m pip install --upgrade pip
python build.py build
```

## <a name="Run_mssql-cli_From_Source_Code"></a>4. Run mssql-cli From Source Code

##### Windows
```
<workspaceRoot>\env\scripts\activate.bat

cd <workspaceRoot>
mssql-cli -S <hostname> -d <database> -U <username>
```
##### MacOS/Linux
```
. <workspaceRoot>/env/bin/activate

cd <workspaceRoot>
. mssql-cli -S <hostname> -d <database> -U <username>
```


## <a name="Run_unit_tests_integration_tests"></a>5. Run Unit Tests / Integration Tests

##### Windows
```
<workspaceRoot>\env\scripts\activate.bat

set MSSQL_CLI_SERVER=<hostname>
set MSSQL_CLI_DATABASE=<database>
set MSSQL_CLI_USER=<username>
set MSSQL_CLI_PASSWORD=<password>

cd <workspaceRoot>
python build.py unit_test
python build.py integration_test
```
##### MacOS/Linux (Python3.x)
```
. <workspaceRoot>/env/bin/activate

export MSSQL_CLI_SERVER=<hostname>
export MSSQL_CLI_DATABASE=<database>
export MSSQL_CLI_USER=<username>
export MSSQL_CLI_PASSWORD=<password>

cd <workspaceRoot>
python3 build.py unit_test
python3 build.py integration_test
```
##### MacOS/Linux (Python2.x)
```
. <workspaceRoot>/env/bin/activate

export MSSQL_CLI_SERVER=<hostname>
export MSSQL_CLI_DATABASE=<database>
export MSSQL_CLI_USER=<username>
export MSSQL_CLI_PASSWORD=<password>

cd <workspaceRoot>
python build.py unit_test
python build.py integration_test
```


# <a name="IDE_Setup"></a>IDE Setup
## <a name="Install_Visual_Studio_Code"></a> 1. Install Visual Studio Code
1. Install Visual Studio Code
2. Install the the VS Code [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)

The repo has a launch.json file that will launch the version of Python that is first on your path.
## 2. <a name="Configure_Python_Settings_in_Visual_Studio_Code"></a> Configure Python Settings in Visual Studio Code

## <a name="Running_Tests"></a>4. Running Tests
Provided your PYTHONPATH was set correctly, you can run the tests from your `<clone_root>` directory.
### 1. Activate VSCode Python Extension
Open the workspace folder with VS Code. The python extension is not active yet as in the screenshot.

1. Run unit tests:

**Note**: You must first set the target server and database information connection info via environment variables:
##### Windows
```
set MSSQL_CLI_SERVER=<Target server name>
set MSSQL_CLI_DATABASE=<Target database name>
set MSSQL_CLI_USER=<User name>
set MSSQL_CLI_PASSWORD=<password>
```

##### MacOSX/Linux (bash)
```
export MSSQL_CLI_SERVER=<Target server name>
export MSSQL_CLI_DATABASE=<Target database name>
export MSSQL_CLI_USER=<User name>
export MSSQL_CLI_PASSWORD=<password>
```

Execute the unit tests.
```
python build.py unit_test
```

2. Run integration tests (code format, unit tests, packaging, integration,) with tox:

```
python build.py integration_test
```

## <a name="Run_mssql-cli"></a>5. Running mssql-cli
#### Command line

1. Invoke mssql-cli using:

##### MacOS/Linux (bash):
```
mssql-cli --help
```

##### Windows:
```
<clone_root>\mssql-cli.bat --help
```
which is equivalent to the following:
```
python -m mssql-cli --help
```
![image](https://user-images.githubusercontent.com/19577035/63064795-f928bd00-beb7-11e9-8d53-64840a7a8dcb.png)

In order to activate the python extension, select one of the `*.py` file in the explorer on the left.
You will see the extension becomes active and showes current version of python hooked up to the extension by default.

![image](https://user-images.githubusercontent.com/19577035/63064822-1eb5c680-beb8-11e9-8f22-0d3ddad25a95.png)



### 2. Create .env file
geleems marked this conversation as resolved.
Show resolved Hide resolved
Create a file named `<workspaceRoot>/.env` with contents:
```
MSSQL_CLI_SERVER=<hostname>
MSSQL_CLI_DATABASE=<database>
MSSQL_CLI_USER=<username>
MSSQL_CLI_PASSWORD=<password>
```


## <a name="How_To_Run_mssql_cli_With_Debugger"></a> 3. How To Run mssql_cli With Debugger

Select `Python: Launch mssql-cli` and click the green arrow in order to launch mssql-cli debugger.
![image](https://user-images.githubusercontent.com/19577035/63066602-c97db300-bebf-11e9-83ce-f2bfe30c49c1.png)
Debugger will run successfully as shown below.
![image](https://user-images.githubusercontent.com/19577035/63066946-87ee0780-bec1-11e9-9b3b-2897d15a651b.png)


## <a name="How_To_Run_Unit_Tests_With_Without_Debugger"></a> 4. How To Run Unit Tests With / Without Debugger
### 1. Discover All Unit Tests Of Project In VSCode
Click `Run Tests` on the bottom of VSCode, and select `Discover Tests` among the test menu.
![image](https://user-images.githubusercontent.com/19577035/63067638-c0dbab80-bec4-11e9-8f49-2d407f929813.png)

You can see all the discovered unit tests after discover process finishes. A test or a group of tests can be executed by one-click in VSCode as shown below.
![image](https://user-images.githubusercontent.com/19577035/63067720-2039bb80-bec5-11e9-8007-f44a8796aa3b.png)

### 2. Run Unit Test In VSCode
Run unit tests as shown below.
![image](https://user-images.githubusercontent.com/19577035/63145132-ffe42c80-bfaa-11e9-9afe-c7fbf5424930.png)


### 3. Run Unit Test With Debugger
Clicking `Debug Test` will start debugger for a corresponding unit test as shown below.
![image](https://user-images.githubusercontent.com/19577035/63067893-f59c3280-bec5-11e9-8874-6e22821fb608.png)