saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-17 10:10:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge pull request #22813 from twangboy/win_doc_fix

Browse source 
Updated instructions for building salt
This commit is contained in:
Justin Findlay 2015-04-17 22:10:07 -06:00
commit e99f2fdb28
1 changed files with 274 additions and 89 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

363
doc/topics/installation/windows.rst
View file

@ -165,7 +165,7 @@ line. The options `/master` and `/minion-name` allow for configuring the master
hostname and minion name, respectively. Here's an example of using the silent
installer:
.. code-block:: bash
.. code-block:: bat
Salt-Minion-0.17.0-Setup-amd64.exe /S /master=yoursaltmaster /minion-name=yourminionname
@ -173,118 +173,305 @@ installer:
Setting up a Windows build environment
======================================
1. Install the Microsoft Visual C++ 2008 SP1 Redistributable, `vcredist_x86`_
or `vcredist_x64`_.
This document will explain how to set up a development environment for salt on
Windows. The development environment allows you to work with the source code to
customize or fix bugs. It will also allow you to build your own installation.
2. Install `msysgit`_
The Easy Way
------------
3. Clone the Salt git repository from GitHub
.. code-block:: bash
Prerequisite Software
^^^^^^^^^^^^^^^^^^^^^
git clone git://github.com/saltstack/salt.git
To do this the easy way you only need to install `Git for Windows <https://github.com/msysgit/msysgit/releases/download/Git-1.9.5-preview20150319/Git-1.9.5-preview20150319.exe/>`_.
4. Install the latest point release of `Python 2.7`_ for the architecture you
wish to target
Create the Build Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5. Add C:\\Python27 and C:\\Python27\\Scripts to your system path
1. Clone the `Salt-Windows-Dev <https://github.com/saltstack/salt-windows-dev/>`_
repo from github.
6. Download and run the Setuptools bootstrap - `ez_setup.py`_
Open a command line and type:
.. code-block:: bash
.. code-block:: bat
python ez_setup.py
7. Install Pip
git clone https://github.com/saltstack/salt-windows-dev
.. code-block:: bash
easy_install pip
2. Build the Python Environment
8. Install the latest point release of `OpenSSL for Windows`_
Go into the salt-windows-dev directory. Right-click the file named
**dev_env.ps1** and select **Run with PowerShell**
#. During setup, choose first option to install in Windows system
directory
If you get an error, you may need to change the execution policy.
9. Install the latest point release of `M2Crypto`_
Open a powershell window and type the following:
#. In general, be sure to download installers targeted at py2.7 for your
chosen architecture
.. code-block:: powershell
10. Install the latest point release of `pycrypto`_
Set-ExecutionPolicy RemoteSigned
11. Install the latest point release of `pywin32`_
This will download and install Python with all the dependencies needed to
develop and build salt.
12. Install the latest point release of `Cython`_
3. Build the Salt Environment
13. Install the latest point release of `jinja2`_
Right-click on the file named **dev_env_salt.ps1** and select **Run with
Powershell**
14. Install the latest point release of `msgpack`_
This will clone salt into ``C:\Salt-Dev\salt`` and set it to the 2015.2
branch. You could optionally run the command from a powershell window with a
``-Version`` switch to pull a different version. For example:
15. Install psutil
.. code-block:: powershell
.. code-block:: bash
dev_env_salt.ps1 -Version '2014.7'
easy_install psutil
To view a list of available branches and tags, open a command prompt in your
`C:\Salt-Dev\salt` directory and type:
16. Install pyzmq
.. code-block:: bat
.. code-block:: bash
easy_install pyzmq
17. Install PyYAML
.. code-block:: bash
easy_install pyyaml
18. Install bbfreeze
.. code-block:: bash
easy_install bbfreeze
19. Install wmi
.. code-block:: bash
pip install wmi
20. Install esky
.. code-block:: bash
pip install esky
21. Install Salt
.. code-block:: bash
cd salt
python setup.py install
22. Build a frozen binary distribution of Salt
.. code-block:: bash
python setup.py bdist_esky
A zip file has been created in the ``dist/`` folder, containing a frozen copy
of Python and the dependency libraries, along with Windows executables for each
of the Salt scripts.
git branch -a
git tag -n
Building the installer
======================
The Hard Way
------------
The Salt Windows installer is built with the open-source NSIS compiler. The
source for the installer is found in the pkg directory of the Salt repo here:
:blob:`pkg/windows/installer/Salt-Minion-Setup.nsi`. To create the installer,
extract the frozen archive from ``dist/`` into ``pkg/windows/buildenv/`` and
run NSIS.
Prerequisite Software
^^^^^^^^^^^^^^^^^^^^^
The NSIS installer can be found here: http://nsis.sourceforge.net/Main_Page
Install the following software:
1. `Git for Windows <https://github.com/msysgit/msysgit/releases/download/Git-1.9.5-preview20150319/Git-1.9.5-preview20150319.exe/>`_
2. `Nullsoft Installer <http://downloads.sourceforge.net/project/nsis/NSIS%203%20Pre-release/3.0b1/nsis-3.0b1-setup.exe/>`_
Download the Prerequisite zip file for your CPU architecture from the
SaltStack download site:
* `Salt32.zip <http://docs.saltstack.com/downloads/windows-deps/Salt32.zip/>`_
* `Salt64.zip <http://docs.saltstack.com/downloads/windows-deps/Salt64.zip/>`_
These files contain all sofware required to build and develop salt. Unzip the
contents of the file to ``C:\Salt-Dev\temp``.
Create the Build Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Build the Python Environment
* Install Python:
Browse to the ``C:\Salt-Dev\temp`` directory and find the Python
installation file for your CPU Architecture under the corresponding
subfolder. Double-click the file to install python.
Make sure the following are in your **PATH** environment variable:
.. code-block:: bat
C:\Python27
C:\Python27\Scripts
* Install Pip
Open a command prompt and navigate to ``C:\Salt-Dev\temp``
Run the following command:
.. code-block:: bat
python get-pip.py
* Easy Install compiled binaries.
M2Crypto, PyCrypto, and PyWin32 need to be installed using Easy Install.
Open a command prompt and navigate to ``C:\Salt-Dev\temp\<cpuarch>``.
Run the following commands:
.. code-block:: bat
easy_install -Z <M2Crypto file name>
easy_install -Z <PyCrypto file name>
easy_install -Z <PyWin32 file name>
.. note::
You can type the first part of the file name and then press the tab key
to auto-complete the name of the file.
* Pip Install Additional Prerequisites
All remaining prerequisites need to be pip installed. These prerequisites
are as follow:
* MarkupSafe
* Jinja
* MsgPack
* PSUtil
* PyYAML
* PyZMQ
* WMI
* Requests
* Certifi
Open a command prompt and navigate to ``C:\Salt-Dev\temp``. Run the following
commands:
.. code-block:: bat
pip install <cpuarch>\<MarkupSafe file name>
pip install <Jinja file name>
pip install <cpuarch>\<MsgPack file name>
pip install <cpuarch>\<psutil file name>
pip install <cpuarch>\<PyYAML file name>
pip install <cpuarch>\<pyzmq file name>
pip install <WMI file name>
pip install <requests file name>
pip install <certifi file name>
2. Build the Salt Environment
* Clone Salt
Open a command prompt and navigate to ``C:\Salt-Dev``. Run the following command
to clone salt:
.. code-block:: bat
git clone https://github.com/saltstack/salt
* Checkout Branch
Checkout the branch or tag of salt you want to work on or build. Open a
command prompt and navigate to ``C:\Salt-Dev\salt``. Get a list of
available tags and branches by running the following commands:
.. code-block:: bat
git fetch --all
To view a list of available branches:
git branch -a
To view a list of availabel tags:
git tag -n
Checkout the branch or tag by typing the following command:
.. code-block:: bat
git checkout <branch/tag name>
* Clean the Environment
When switching between branches residual files can be left behind that
will interfere with the functionality of salt. Therefore, after you check
out the branch you want to work on, type the following commands to clean
the salt environment:
.. code-block: bat
git clean -fxd
git reset --hard HEAD
Developing with Salt
====================
There are two ways to develop with salt. You can run salt's setup.py each time
you make a change to source code or you can use the setup tools develop mode.
Configure the Minion
--------------------
Both methods require that the minion configuration be in the ``C:\salt``
directory. Copy the conf and var directories from ``C:\Salt-Dev\salt\pkg\
windows\buildenv`` to ``C:\salt``. Now go into the ``C:\salt\conf`` directory
and edit the file name ``minion`` (no extension). You need to configure the
master and id parameters in this file. Edit the following lines:
.. code-block:: bat
master: <ip or name of your master>
id: <name of your minion>
Setup.py Method
---------------
Go into the ``C:\Salt-Dev\salt`` directory from a cmd prompt and type:
.. code-block:: bat
python setup.py install --force
This will install python into your python installation at ``C:\Python27``.
Everytime you make an edit to your source code, you'll have to stop the minion,
run the setup, and start the minion.
To start the salt-minion go into ``C:\Python27\Scripts`` from a cmd prompt and
type:
.. code-block:: bat
salt-minion
For debug mode type:
.. code-block:: bat
salt-minion -l debug
To stop the minion press Ctrl+C.
Setup Tools Develop Mode (Preferred Method)
-------------------------------------------
To use the Setup Tools Develop Mode go into ``C:\Salt-Dev\salt`` from a cmd
prompt and type:
.. code-block:: bat
pip install -e .
This will install pointers to your source code that resides at
``C:\Salt-Dev\salt``. When you edit your source code you only have to restart
the minion.
Build the windows installer
===========================
This is the method of building the installer as of version 2014.7.4.
Clean the Environment
---------------------
Make sure you don't have any leftover salt files from previous versions of salt
in your Python directory.
1. Remove all files that start with salt in the ``C:\Python27\Scripts``
directory
2. Remove all files and directorys that start with salt in the
``C:\Python27\Lib\site-packages`` directory
Install Salt
------------
Install salt using salt's setup.py. From the ``C:\Salt-Dev\salt`` directory
type the following command:
.. code-block:: bat
python setup.py install --force
Build the Installer
-------------------
From cmd prompt go into the ``C:\Salt-Dev\salt\pkg\windows`` directory. Type
the following command for the branch or tag of salt you're building:
.. code-block:: bat
BuildSalt.bat <branch or tag>
This will copy python with salt installed to the ``buildenv\bin`` directory,
make it portable, and then create the windows installer . The .exe for the
windows installer will be placed in the ``installer`` directory.
Testing the Salt minion
@ -339,7 +526,7 @@ salt, including all dependencies:
This script is not up to date. Please use the installer found above
.. code-block:: bash
.. code-block:: powershell
# (All in one line.)
@ -363,8 +550,6 @@ this, salt-minion can't report some installed softwares.
.. _http://csa-net.dk/salt: http://csa-net.dk/salt
.. _vcredist_x86: http://www.microsoft.com/en-us/download/details.aspx?id=5582
.. _vcredist_x64: http://www.microsoft.com/en-us/download/details.aspx?id=2092
.. _msysgit: http://code.google.com/p/msysgit/downloads/list?can=3
.. _Python 2.7: http://www.python.org/downloads
.. _ez_setup.py: https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py