From 037e7cc02b66a54d5dec19a6b93a7bf107a95a0e Mon Sep 17 00:00:00 2001
From: gcontini <1121667+gcontini@users.noreply.github.com>
Date: 周六, 28 3月 2020 22:29:12 +0800
Subject: [PATCH] documentation update (win32) and others
---
/dev/null | 35 --------
doc/analysis/features.rst | 8 +
doc/api/extend.rst | 2
doc/analysis/Backoffice.txt | 0
doc/development/Build-the-library-windows.rst | 104 ++++++++++++++++++++++++++
README.md | 4
doc/development/CMakeSettings.json | 24 ++++++
doc/index.rst | 11 ++
doc/usage/integration.rst | 41 ++++++++++
9 files changed, 188 insertions(+), 41 deletions(-)
diff --git a/README.md b/README.md
index 7cf6418..567a849 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
machines, or prevent the usage in virtualized environments. It is an Open License Manager that helps to keep your
software closed :smirk: . Among other features if it runs on a "real hardware" it can generate a signature of that hardware and report if the signature doesn't match.
-A comprehensive [list of features](https://github.com/open-license-manager/open-license-manager/wiki/features), and their status is available in the project wiki.
+A comprehensive [list of features](http://open-license-manager.github.io/open-license-manager/analysis/features.html), and their status is available in the project wiki.
If you plan to use this library or part of it remember to show us your appreciation giving it a
<a class="github-button" href="https://github.com/open-license-manager/open-license-manager" data-icon="octicon-star" aria-label="Star open-license-manager/open-license-manager on GitHub">star</a> here on GitHub.
@@ -39,7 +39,7 @@
- tools : cmake(>3.6), git, make/ninja(linux)
- libs : If target is Linux Openssl is required. Windows depends only on system libraries. Boost is necessary to build license generator and to run the tests but it's NOT a dependency of the final `licensecc` library.
-For a complete list of dependencies and supported environments see [the wiki](https://github.com/open-license-manager/open-license-manager/wiki/Dependencies)
+For a complete list of dependencies and supported environments see [the wiki](http://open-license-manager.github.io/open-license-manager/development/Dependencies.html)
Clone the project. It has submodules, don't forget the `--recursive` option.
diff --git a/doc/analysis/Backoffice.md b/doc/analysis/Backoffice.txt
similarity index 100%
rename from doc/analysis/Backoffice.md
rename to doc/analysis/Backoffice.txt
diff --git a/doc/analysis/features.rst b/doc/analysis/features.rst
index 02309c6..9fb1bdf 100644
--- a/doc/analysis/features.rst
+++ b/doc/analysis/features.rst
@@ -2,7 +2,13 @@
Features
###########
-features and their status
+Licensecc is suitable for your project if it is relatively small, you plan to distribute it in a demo version and you
+estimate there will be a "limited" number of clients:
+
+* The management of licenses is command-line. If you plan to issue hundreds of licenses you should consider more advanced licensing systems.
+* Open License Manager doesn't offer professional support.
+
+Features and their status
****************************
====================================== ========================
diff --git a/doc/api/extend.rst b/doc/api/extend.rst
index 2dbfaa7..4badcb7 100644
--- a/doc/api/extend.rst
+++ b/doc/api/extend.rst
@@ -10,7 +10,7 @@
You've found the provided hardware signatures don't behave well for your customers (we can test on a limited set of
hardware we've receiving reports of usage on environments we never imagined before).
You can either change the way the default strategy behaves (choose for instance cpu type over disk label as default) or
-invent your own identification method.
+provide your own identification method.
.. toctree::
diff --git a/doc/development/Build-the-library-windows.md b/doc/development/Build-the-library-windows.md
deleted file mode 100644
index e9a8719..0000000
--- a/doc/development/Build-the-library-windows.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# Build - Windows
-
-This page describes how to build the library. Under windows both MSVC compiler and MinGW are supported
-
-## MSVC (2015~2019) - prerequisites
-Pre-compiled [versions of boost](https://sourceforge.net/projects/boost/files/boost-binaries/) for windows are available at SourceForge.
-
-For MSVC 2019: recommended cmake => 3.15.2 (the version 3.14 embedded in visual studio is not working with boost 1.71),
-[boost 1.71 msvc-14.2](https://dl.bintray.com/boostorg/release/1.71.0/binaries/boost_1_71_0-msvc-14.2-64.exe)
-
-### Checkout the code
-This project has a submodule (the license generator). Remember to add the option `--recursive` to clone it.
-
-```console
-git clone --recursive https://github.com/open-license-manager/open-license-manager.git
-```
-
-~~Initialize command line tools:~~
-
-```
-~~ "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64 ~~
-```
-
-Configure the library:
-
-```
-cmake .. -G "Visual Studio 16 2019" -A x64 -DBOOST_ROOT="C:\local\boost" //(or where boost was installed)
-```
-
-### Supported cmake definitions/options
-Below a list of some useful cmake configurations:
-
-|Definition name|Description|
-|---------------|-----------|
-|-DSTATIC_RUNTIME=1 |link statically to the standard and runtime support libraries (compiler flag /MT)|
-|-DCMAKE_BUILD_TYPE=Release|link to the release version of the boost libraries|
-|-DCMAKE_INSTALL_PREFIX=C:\.. | folder where to install libraries and headers |
-|-DBOOST_ROOT=C:\.. | folder where boost is installed. If cmake is reporting boost not found consider updating cmake. |
-
-Compile and test (command line)
-
-```
-cmake --build . --target install --config Release
-
-ctest -C Release
-```
diff --git a/doc/development/Build-the-library-windows.rst b/doc/development/Build-the-library-windows.rst
new file mode 100644
index 0000000..a8b42e6
--- /dev/null
+++ b/doc/development/Build-the-library-windows.rst
@@ -0,0 +1,104 @@
+#######################################
+Build - Windows
+#######################################
+
+This page describes how to build the library under windows. Both MSVC compiler and MinGW are supported.
+
+
+MSVC (2015~2019)
+*****************
+
+MSVC install prerequisites
+=============================
+Git is of course a prerequisite, if you don't have it you can download it from git-scm.com (here is a )
+
+Pre-compiled `versions of boost <https://sourceforge.net/projects/boost/files/boost-binaries/>`_ for windows are available
+at SourceForge. Choose the version that matches the desired architecture (eg. for Visual Studio 2019 64 bit you can download
+`boost 1.71 msvc-14.2 <https://dl.bintray.com/boostorg/release/1.71.0/binaries/boost_1_71_0-msvc-14.2-64.exe>`_ ) or
+if unsure download the full `boost_1_71_0-bin-msvc-all-32-64.7z <https://dl.bintray.com/boostorg/release/1.71.0/binaries/boost_1_71_0-bin-msvc-all-32-64.7z>`_ archive.
+
+With boost 1.71 it is recommended to download one of the `latest cmake <https://github.com/Kitware/CMake/releases/download/v3.17.0/cmake-3.17.0-win64-x64.msi>`_ (>3.16). The version with Visual Studio 2019 isn't the most up to date.
+
+
+Checkout the code
+==================
+Check out the code using git:
+
+.. NOTE::
+
+ This project has a submodule (the license generator). Remember to add the option `--recursive` to clone it.
+
+.. code-block:: console
+
+ git clone --recursive https://github.com/open-license-manager/open-license-manager.git
+
+Compile and build (command line)
+====================================
+
+Open a command prompt in the folder where you checked out the library.
+
+Configure the library (windows x64):
+
+.. code-block:: console
+
+ cd build
+ cmake .. -G "Visual Studio 16 2019" -A x64 -DBOOST_ROOT="C:\local\boost" //(or where boost was installed)
+
+Configure the library (windows x86):
+
+For some configuration reason we're unable to build using x86 using visual studio generators. We recommend to use Ninja
+build system.
+
+.. code-block:: console
+
+ cd build
+ "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x86
+ cmake .. -G "Ninja" -DBOOST_ROOT="C:\local\boost" //(or where boost was installed)
+
+Supported cmake definitions/options
+=======================================
+Below a list of some useful cmake configurations:
+
+============================== ==============================================================================================
+Definition name Description
+============================== ==============================================================================================
+-DSTATIC_RUNTIME=1 link statically to the standard and runtime support libraries (compiler flag /MT)
+-DCMAKE_BUILD_TYPE=Release link to the release version of the boost libraries
+-DCMAKE_INSTALL_PREFIX=C:\.. folder where to install libraries and headers
+-DBOOST_ROOT=C:\.. folder where boost is installed. If cmake is reporting boost not found consider updating cmake.
+============================== ==============================================================================================
+
+Compile and test
+
+.. code-block:: console
+
+ cmake --build . --target install --config Release
+ ctest -C Release
+
+
+Compile and build (Visual studio 2019)
+==========================================
+
+Visual Studio 2019 integrates with CMake (the process requires a couple of restarts and it's all but "fluid").
+
+After opening the project "as a CMake project" a CMakeSettings.json should appear in the base folder. Edit the file as
+below (the file is for an x86 architecture). In a special way:
+
+* remove the "-v" switch from "buildCommandArgs"
+* add the variable BOOST_ROOT pointing to where your boost installation is.
+
+Restart, delete and rebuild the cache a couple of time, until Visual Studio understands the new options
+(tested with Visual Studio 2019 16.5.1).
+
+.. literalinclude:: CMakeSettings.json
+ :language: json
+
+
+MINGW
+*****************
+
+
+.. TODO::
+
+ MINGW documentation need to be done. Refer to file .travis.yml to see a list of commands for windows-mingw
+
diff --git a/doc/development/CMakeSettings.json b/doc/development/CMakeSettings.json
new file mode 100644
index 0000000..2c82981
--- /dev/null
+++ b/doc/development/CMakeSettings.json
@@ -0,0 +1,24 @@
+锘縶
+ "configurations": [
+ {
+ "name": "x86-Debug",
+ "generator": "Visual Studio 16 2019",
+ "configurationType": "Debug",
+ "buildRoot": "${projectDir}\\out\\build\\${name}",
+ "installRoot": "${projectDir}\\out\\install\\${name}",
+ "cmakeExecutable": "C:/Program Files/CMake/bin/cmake.exe",
+ "cmakeCommandArgs": "",
+ "buildCommandArgs": "",
+ "ctestCommandArgs": "",
+ "inheritEnvironments": [ "msvc_x86" ],
+ "intelliSenseMode": "windows-msvc-x86",
+ "variables": [
+ {
+ "name": "BOOST_ROOT",
+ "value": "F:/boost_1_71_0",
+ "type": "PATH"
+ }
+ ]
+ }
+ ]
+}
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
index 69b5e14..578918b 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -39,11 +39,12 @@
Project Structure
*******************
-The software is made by 3 main sub-components:
+The software is made by 4 main sub-components:
* ``licensecc`` : the C++ library with a C api (the part you have to integrate in your software) with minimal (or no) external dependencies. This is the project you're currently looking at.
* ``lccinspector`` : a license debugger to be sent to the final customer to diagnose licensing problems or for calculating the pc hash before issuing the license.
* ``lccgen`` : a license generator (github project `lcc-license-generator`_ ) to initialize the library and generate the licenses.
+* ``examples`` : usage samples (github project `examples <https://github.com/open-license-manager/examples>`_ ).
.. _lcc-license-generator: https://github.com/open-license-manager/lcc-license-generator
@@ -115,10 +116,16 @@
How to use
**************
-The `examples`_ repository shows various ways to integrate `licensecc` into your project.
+The `examples`_ repository shows various ways to integrate ``licensecc`` into your project.
.. _examples: https://github.com/open-license-manager/examples
+Branches and status
+*********************
+
+* On branch ``master`` there is the 'legacy' 1.0.0 version. This version is working but doesn't correspond to the current documentation, and we don't plan to actively fix it. There are well-known bugs and limitations. We still accept community contributions on this branch. Feel free to propose your pull request.
+* On branch ``develop`` there is the upcoming 2.0.0 version that corresponds to the documentation. This version is under development and has not been extensively used/tested. However we encourage users to download and use this one.
+
How to contribute
********************
diff --git a/doc/usage/integration.md b/doc/usage/integration.md
deleted file mode 100644
index 4274185..0000000
--- a/doc/usage/integration.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Integrate license in your application
-
-This short guide explain how to integrate `open-license-manager` in your application.
-
-Working examples are provided in the [examples](https://github.com/open-license-manager/examples) project.
-
-## Public api
-The file containing the public api is `include/licensecc/licensecc.h`. Functions in there are considered stable.
-
-
-### Print a hardware identifier
-
-```CPP
-bool identify_pc(IDENTIFICATION_STRATEGY pc_id_method, char* identifier_out, size_t bufSize);
-```
-
-### Verify a license
-
-```CPP
-/**
- * This method is used to request the use of one license for a product.
- * In case of local license it's used to check if the product is licensed.
- *
- * @return LICENSE_OK(0) if successful. Other values if there are errors.
- * @param productName[in]
- * a vendor defined string containing the name of the product we want to request.
- * @param licenseLocation[in] otpional, can be NULL.
- * licenseLocation, either the name of the file
- * or the name of the environment variable should be !='\0'
- * @param license[out] optional, can be NULL, if set it will return extra informations about the license.
- */
-
-EVENT_TYPE acquire_license(const CallerInformations* callerInformation, const LicenseLocation* licenseLocation,
- LicenseInfo* license_out);
-```
\ No newline at end of file
diff --git a/doc/usage/integration.rst b/doc/usage/integration.rst
new file mode 100644
index 0000000..770567d
--- /dev/null
+++ b/doc/usage/integration.rst
@@ -0,0 +1,41 @@
+#########################################
+Integrate Licensecc in your application
+#########################################
+
+This short guide explain how to integrate `open-license-manager` in your application.
+
+Working examples are provided in the `examples <https://github.com/open-license-manager/examples>`_ project.
+
+Build System - locate and link the licensecc
+*********************************************
+
+We strongly recommend to use CMake as a build system.
+If this is the case, the easiest way to compile is to configure LicenseCC as a git submodule of your project.
+
+Then you can copy the cmake module ``Findlicensecc.cmake`` into your cmake modules directory in order to be able to
+locate the compiled library.
+
+Adding the following lines to your ``CMakeLists.txt``
+
+.. code-block:: console
+
+ find_package(licensecc 2.0.0 REQUIRED)
+
+will make the external target ``licensecc::licensecc_static`` to be available for linking.
+
+``Findlicensecc.cmake`` takes the following CMake variables as input.
+
+==================== ====================
+Cmake variable Description
+==================== ====================
+LICENSECC_LOCATION | If licensecc was not checked out as a git submodule, in this variable you can provide an hint
+ | to locate the library. It may point to the installation folder or the source folder.
+LCC_PROJECT_NAME | Name of the project (the software where you want to integrate licensecc).
+ | Alternatively it is possible to specify a component name in the component section of find_package.
+==================== ====================
+
+Call Licensecc from your code
+*******************************
+The file containing the public api is ``include/licensecc/licensecc.h``. Functions in there are considered stable.
+
+refer to :ref:`public api <api/public_api:Public api>` to understand how to generate an hardware identifer or validate a license.
--
Gitblit v1.9.1