Skip to content

Latest commit

 

History

History
153 lines (123 loc) · 5.4 KB

development_guide.md

File metadata and controls

153 lines (123 loc) · 5.4 KB
Raw

Development Guide

Table of Contents

  1. Preparing your machine
  2. Environment Setup
  3. Configuring IDE
  4. Running Tests
  5. Running mssql-scripter
  6. Packaging

See the Architecture Guide for details on how mssql-scripter is designed and implemented.

mssql-scripter sources are located on GitHub (https://github.com/Microsoft/mssql-scripter). In order to contribute to the project, you are expected to:

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.

    Windows

    • The latest Python installation package can be downloaded from here.
    • 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/Microsoft/mssql-scripter

2. Environment Setup

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.

If not developing in a virtual environment, please proceed to Development Setup

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

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 clean

3. Configuring your IDE

Visual Studio (Windows only)

  1. Install Python Tools for Visual Studio
  2. Open the <clone_root>\mssql-scripter.pyproj project in Visual Studio

Visual Studio Code (Any platform)

  1. Install VS Code
  2. Install the the VS Code Python extension

The repo has a launch.json file that will launch the version of Python that is first on your path.

4. Running Tests

Provided your PYTHONPATH was set correctly, you can run the tests from your <clone_root> directory.

  1. Run end to end tests (code format, unit tests, packaging, integration,) with tox:

    tox

    Note: Tox is used run full suite of tests in each python version. Running the command above will run the full suite of tests against Python 2.7 and Python 3.6, if installed. More info can be found at tox testing.

    Run tox tests against specific Python version:

    tox -e py27
tox -e py36

    Recommended: Recreate virtual environment on each run to ensure tests are not executing against cached changes.

    tox --recreate -e py27
tox --recreate -e py36

  2. Run unit tests with code coverage only:

    pytest --cov mssqlscripter

  3. Running tests for specific components:

    To test the mssqlscripter:

    pytest mssqlscripter/tests

    To test the jsonrpc library:

    pytest mssqlscripter/jsonrpc/tests

    To test the scripting service:

    pytest mssqlscripter/jsonrpc/contracts/tests

5. Running mssql-scripter

Command line

  1. Invoke mssql-scripter using:

    MacOS/Linux (bash):
    mssql-scripter -h
    Windows:
    <clone_root>\mssql-scripter.bat -h

    which is equivalent to the following:

    python -m mssqlscripter -h