1=============================== 2Building and developing pymssql 3=============================== 4 5Building 6======== 7 8To build pymssql you should have: 9 10* Python >= 2.7 including development files. Please research your OS usual 11 software distribution channels, e.g, ``python-dev`` or ``python-devel`` 12 packages. 13* Cython >= 0.19.1 14* FreeTDS >= 0.91 including development files. Please research your OS usual 15 software distribution channels, e.g, ``freetds-dev`` or ``freetds-devel`` 16 packages. 17* Microsoft SQL Server 18 19.. note:: 20 If developing on Windows you will want to make sure you install debug symbols. 21 For more information see https://docs.python.org/3/using/windows.html#installation-steps 22.. note:: 23 If you need to connect to Azure make sure FreeTDS is built with SSL support. 24 Instructions on how to do this are out of the scope of this document. 25 26Windows 27------- 28 29 30Required Tools 31______________ 32In addition to the requirements above when developing ``pymssql`` on the Windows 33platform you will need these additional tools installed: 34 35* Visual Studio C++ Compiler Tools 36* Developer Command Prompt for Visual Studio 37* `Cmake <https://cmake.org/download/>`_ 38* `7Zip <https://www.7-zip.org/download.html>`_ 39 40For C++ and the Developer Command Prompt the easiest path is installing Visual Studio. 41When installing make sure you select the C++ libraries and components. Also make sure that 42Visual Studio installs nmake with the C++ library installs. 43 44* https://visualstudio.microsoft.com/vs/community/ 45 46.. note:: 47 One thing to be aware of is which version of Python you are using relative to which 48 C++ compilers you have installed. When building on Windows you should make sure you 49 have the required compiler, pip and setuptools versions installed. For more 50 information see https://wiki.python.org/moin/WindowsCompilers 51 52 53Required Libraries 54__________________ 55 56Developing ``pymssql`` on Windows also requires the following libraries: 57 58* `FreeTDS <http://www.freetds.org/>`_ 59* `iconv <https://www.gnu.org/software/libiconv/>`_ 60 61For development you will want ``freetds`` to be available in your project path. 62You can find prebuilt artifacts at the `FreeTDS Appveyor project <https://ci.appveyor.com/project/FreeTDS/freetds?branch=master>`_ 63 64To download select the job name that matches your environment (platform, version and tds 65version) and then click the artifacts tag. You can download the zip file with or without 66ssl depending on your needs. 67 68 69.. note:: 70 Remove the existing ``freetds0.95`` directory in the ``pymssql`` project directory 71 72Extract the .zip artifact into your project path into a directory named ``freetds`` 73 74 ``C:\\%USERPATH%\\pymssql\\freetds`` 75 76You will also need to remove the branch tag from the artifact directory (for instance 77``master`` from ``vs2015_64-master``) or update the ``INCLUDE`` and ``LIB`` environment 78variables so that the compiler and linker are able to find the path to 79``%PROJECTROOT%\\freetds\\<artifact folder>\\include`` and 80``%PROJECTROOT%\\freetds\\<artifact folder>\\lib`` 81in the build step. 82 83 84.. note:: 85 If you decide to add the directories to ``INCLUDE`` and ``LIB`` the below provide example 86 commands 87 88 .. code-block:: 89 90 set INCLUDE=%INCLUDE%;%USERPROJECTS%\\pymssql\\freetds\\vs2015_64-master\\include 91 92 set LIB=%LIB%;%USERPROJECTS%\\pymssql\\freetds\\vs2015_64-master\\lib 93 94In addition to ``freetds`` you will want ``iconv`` available on your project path. For iconv 95on Windows we recommend https://github.com/win-iconv/win-iconv.git. We will retrieve this in 96an upcoming build step. 97 98If you prefer to build FreeTDS on your own please refer to the FreeTDS `config <http://www.freetds.org/>`_ and 99`os issues <http://www.freetds.org/userguide/osissues.htm>`_ build pages. 100 101 102Required Environment Variables 103______________________________ 104 105You will need to set the following environment variables in 106Visual Studio Developer Command Prompt before installing iconv. 107 108* set PYTHON_VERSION=<Python Version> 109* set PYTHON_ARCH=<Python Architecture> 110* set VS_VER=<MSVC Compiler Version> 111 112Example: 113 114 .. code-block:: 115 116 set PYTHON_VERSION=3.6.6 117 set PYTHON_ARCH=64 118 set VS_VER=2015 119 120 121Installing iconv 122________________ 123 124``pymssql`` expects ``iconv`` header and lib objects and to be available in the ``build\\include`` 125and ``build\\bin`` directories 126 127From the root of your project (pymssql directory) run: 128 129.. code-block:: 130 131 powershell dev\appveyor\install-win-iconv.ps1 132 133This is a powershell script that will download `win-iconv <https://github.com/win-iconv/win-iconv/>`_ 134from the previously mentioned GitHub repository, build and move the artifacts to the 135directory that ``pymssql`` will use with ``Cython``. 136 137.. note:: 138 139 If you receive the following TLS error that is probably due to a mismatch between powershells 140 TLS version and GitHub. 141 142 .. code-block:: 143 144 Exception calling "DownloadFile" with "2" argument(s): "The request was aborted: Could not create SSL/TLS secure channel." 145 146 You can add this line to ``%PROJECTROOT%\\dev\\appveyor\\install-win-iconv.ps1`` 147 148 .. code-block:: PowerShell 149 150 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 151 152 On line 3 and the powershell script should run with TLS1.2. See issue `547 <https://github.com/pymssql/pymssql/issues/547>`_ 153 for more information 154 155 156Required Python Packages 157________________________ 158For Python you will need the following packages installed into your virtual environment: 159 160* Cython 161* pytest == 3.2.5 162* SQLAlchemy 163* wheel 164 165 166Running the build 167_________________ 168 169With the above libraries, pacakges and potential environment variables in place we are ready to 170build. 171 172At the root of the project with your virtual environment activated run 173 174.. code-block:: 175 176 python setup.py build 177 178If there are no errors you are then ready to run 179 180.. code-block:: 181 182 python setup.py install 183 184or continue on to the `Testing`_ documentation which advises using 185 186.. code-block:: 187 188 python setup.py develop. 189 190To report any issues with building on Windows please use the `mailing list <https://groups.google.com/forum/#!forum/pymssql>`_ 191 192 193Unix 194---- 195 196To build on Unix you must also have: 197 198* gcc 199 200Then you can simply run:: 201 202 python setup.py build 203 204or other ``setup.py`` commands as needed. 205 206Testing 207======= 208 209.. danger:: 210 211 ALL DATA IN TESTING DBS WILL BE DELETED !!!! 212 213You will need to install two additional packages for testing:: 214 215 easy_install pytest SQLAlchemy 216 217You should build the package with:: 218 219 python setup.py develop 220 221You need to setup a ``tests.cfg`` file in ``tests/`` with the correct DB 222connection information for your environment:: 223 224 cp tests/tests.cfg.tpl tests/tests.cfg 225 vim|emacs|notepad tests/tests.cfg 226 227To run the tests:: 228 229 cd tests # optional 230 py.test 231 232Which will go through and run all the tests with the settings from the ``DEFAULT`` 233section of ``tests.cfg``. 234 235To run with a different ``tests.cfg`` section:: 236 237 py.test --pymssql-section=<secname> 238 239example:: 240 241 py.test --pymssql-section=AllTestsWillRun 242 243to avoid slow tests:: 244 245 py.test -m "not slow" 246 247to select specific tests to run:: 248 249 py.test tests/test_types.py 250 py.test tests/test_types.py tests/test_sprocs.py 251 py.test tests/test_types.py::TestTypes 252 py.test tests/test_types.py::TestTypes::test_image 253