From 3597d8cb717acc31c9f2e8ac256dbe88ae030b19 Mon Sep 17 00:00:00 2001
From: Gabriele Contini <contini.mailing@gmail.com>
Date: 周日, 22 3月 2020 11:51:31 +0800
Subject: [PATCH] improve documentation
---
doc/conf.py | 4
/dev/null | 99 -------------------
doc/analysis/features.rst | 129 +++++++++++++++++++++++++
doc/api/hardware_identifiers.rst | 2
.travis.yml | 2
cmake/Findlccgen.cmake | 0
doc/api/extend.rst | 4
README.md | 10 +
doc/index.rst | 9 +
9 files changed, 149 insertions(+), 110 deletions(-)
diff --git a/.travis.yml b/.travis.yml
index d2cfeff..e432aa0 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -210,7 +210,7 @@
- doxygen
- graphviz
before_script:
- - pip3 install setuptools sphinx sphinx_rtd_theme breathe sphinx-markdown-tables recommonmark sphinx-rtd-theme sphinx-sitemap
+ - pip3 install setuptools sphinx sphinx_rtd_theme breathe sphinx-markdown-tables recommonmark sphinx-rtd-theme sphinx-sitemap sphinxemoji
- cd build && cmake -DCMAKE_INSTALL_PREFIX=../../install ..
script:
- make documentation
diff --git a/README.md b/README.md
index 8124392..7cf6418 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,8 @@
- a license generator (github project [lcc-license-generator](https://github.com/open-license-manager/lcc-license-generator)) `lcc` for customizing the library and generate the licenses.
## How to build
-Below an overview of the basic build procedure, you can find detailed instructions for [linux](https://github.com/open-license-manager/open-license-manager/wiki/Build-the-library) or [windows](https://github.com/open-license-manager/open-license-manager/wiki/Build-the-library-windows) in the wiki.
+Below an overview of the basic build procedure, you can find detailed instructions for [linux](http://open-license-manager.github.io/open-license-manager/development/Build-the-library.html)
+or [windows](http://open-license-manager.github.io/open-license-manager/development/Build-the-library-windows.html) in the project web site.
### Prerequisites
- Operating system: Linux(Ubuntu, CentOS), Windows
@@ -91,5 +92,8 @@
## How to contribute
-The easiest way you can solve your problems or ask help is through the [forum](https://groups.google.com/forum/#!forum/licensecc), otherwise if you think there is a problem you can open an issue in the [issue system](https://github.com/open-license-manager/open-license-manager/issues). Have a look to the [contribution guidelines](CONTRIBUTING.md) before reporting.
-We use [GitFlow](https://datasift.github.io/gitflow/IntroducingGitFlow.html) (or at least a subset of it). Remember to install the gitflow git plugin and use `develop` as default branch for your pull requests.
+The easiest way you can solve your problems or ask help is through the [forum](https://groups.google.com/forum/#!forum/licensecc) (hosted on Google),
+otherwise if you think there is a problem you can open an issue in the [issue system](https://github.com/open-license-manager/open-license-manager/issues).
+Have a look to the [contribution guidelines](CONTRIBUTING.md) before reporting.
+We use [GitFlow](https://datasift.github.io/gitflow/IntroducingGitFlow.html) (or at least a subset of it).
+Remember to install the gitflow git plugin and use `develop` as default branch for your pull requests.
diff --git a/cmake/Findlcc.cmake b/cmake/Findlccgen.cmake
similarity index 100%
rename from cmake/Findlcc.cmake
rename to cmake/Findlccgen.cmake
diff --git a/doc/analysis/features.md b/doc/analysis/features.md
deleted file mode 100644
index 741566d..0000000
--- a/doc/analysis/features.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# Features
-
-## features and their status
-
-| Feature | Implementation status |
-|--------------------------------------|:---------------------:|
-| Trial license with expiry date | :heavy_check_mark: |
-| Link software to "physical" hardware | :heavy_check_mark: |
-| Virtual machine detection | In progress |
-| Easy license retrieval | :heavy_check_mark: |
-| Manage licenses | Planned |
-| Easy Customizable limits | Planned |
-| Java/C# bindings | Planned |
-| Floating/network licenses | Planned |
-
-### Issue a "demo" license with only expiry date.
-Software editors often want to release a trial license that is not linked to a specified machine, but just limit the usage in time or to some other feature (number of cpu, process memory).
-See [execution limits](Implemented/Planned execution limits) section.
-
-### Licenses linked to "physical" hardware id
-Link the software to a physical hardware (a pc). In this scenario the software editor wants his software to be executed on a specific piece of hardware. We suppose the operating system is installed "bare to metal" and we're able to calculate an identifier of that hardware. This isn't always true for virtualized environments for which alternative strategies must be planned [eg. floating licenses (not yet implemented)]. See the section on [hardware identifiers](../usage/Hardware-identifiers) for a detailed discussion of the use cases.
-
-Depending on the situation there are are different kinds of hardware id that can be used. See [execution limits](Implemented/Planned execution limits) section.
-
-### Virtual machine detection
-Detect if the software is running in a virtualized environment and (optionally) forbid the execution. This is useful if software editors want to prevent the execution in virtual machines (lxc/dockers...) and be able to compute a meaningful hardware id.
-Another use case is the software is to be used only in a specific class of virtualized environments. For instance it was initially packaged as a docker image, the software editor don't want it to be "extracted" and placed elsewhere.
-
-### Licenses retrieval
-Open License Manager, when integrated into a licensed software will find its license file based on many different strategies.
-It can handle multiple licenses at the same time. See the wiki page about [license retrieval](../usage/License-retrieval) for details.
-
-### Licensed software features (partially implemented)
-A licensed software may be composed by many features (functions) each one activable independently. Licensing system tells the licensed software which features are enabled, and which features are disabled.
-
-### License Management (planned)
-It is necessary to keep track of the licenses that have been issued, of the clients, and their hardware identifier.
-A web application is planned that will provide integration with payment systems to allow licensed software customers to buy licenses.
-
-### Customizable execution limits (planned)
-It should be easy to add and implement your own "execution limit": that is require/forbid some feature in the application execution environment.
-
-### Java/C# bindings (planned)
-The application should support bindings to java language. The library has to be compiled as a .dll for use with JNI or C# integration layer. This is especially challenging on the api side.
-Since the api is public, and the library is packaged as a separate .dll/.so everybody can compile a version of it always returning LICENSE_OK easily defeating the license schema.
-
-### Floating licenses (planned)
-Limit the execution of the licensed software to a certain number of instances per license.
-This can be done in multiple ways:
- * without a central server, using broadcast or scanning the local network to find peers.
- * with a central server installed in the client's network.
- * with a central server on internet.
-
-Status of this implementation is tracked in [issue #4](https://github.com/open-license-manager/open-license-manager/issues/4)
-
-## Implemented/Planned execution limits
-Open License Manager can limit execution of licensed software based on some criteria, called "execution limits".
-Depending on the execution environment some criteria may not be applicable:
-
-| |Windows BareToMetal | Linux BareToMetal | Linux container (lxc/docker) |Virtual Machine |
-|----------------|:------------------:|:------------------:|:------------------:|:------------------:|
-| date | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| disk label | :heavy_check_mark: | :heavy_check_mark: | :x:<sup>1</sup> | :heavy_check_mark: |
-| disk id | :heavy_check_mark: | :heavy_check_mark: | :x:<sup>1</sup> | :heavy_check_mark: |
-| ip address | :heavy_check_mark: | :heavy_check_mark: | :interrobang: | :heavy_check_mark: |
-| mac address | :heavy_check_mark: | :heavy_check_mark: | :interrobang: | :heavy_check_mark: |
-| cpu number | Planned | Planned | Planned | Planned |
-| process memory | Planned | Planned | Planned | Planned |
-| machine memory | Planned | Planned | Planned | Planned |
-| virtualization type | Planned | Planned | Planned | Planned |
-| concurrent execution | Planned | Planned | Planned | Planned |
-| licensed sw version | Planned | Planned | Planned | Planned |
-
-### Date
-This is the most common limit set on a license, allow the software to expire after the defined date.
-
-### Disk label/Disk id
-It is possible to limit the execution to a computer that has a certain disk connected.
-This feature has been implemented in the `hardware identifier`.
-
-N.B. This kind of limitation doesn't make sense in containerized environments.
-
-### Ip address/Mac address
-It is possible to limit the execution to a computer that has a network card with a spefified MAC address
-(or even we can force to have a specific ip address).
-This feature has been implemented in the `hardware identifier`.
-
-### Cpu Number/Machine memory
-Allow to restrict the execution only to a machine with the specified amount of cpu or memory or less.
-This is useful in virtualized environments, to create a licensed software demo version with limited performaces or with limited scalability.
-Status of this implementation is tracked in [issue #4](https://github.com/open-license-manager/open-license-manager/issues/4)
-
-### Virtualization type
-Allow the execution of the licensed software only on some type of hardware or virtualized environment
-eg. only bare to metal, only in virtual machine, only in docker.
-This feature is being implemented.
-
-### Licensed software version
-A licensed software may declare a version (eg 1.0.0). A license may span multiple releases of the software e.g. allow version 1.1.1 but not 2.0.0.
diff --git a/doc/analysis/features.rst b/doc/analysis/features.rst
new file mode 100644
index 0000000..02309c6
--- /dev/null
+++ b/doc/analysis/features.rst
@@ -0,0 +1,129 @@
+###########
+Features
+###########
+
+features and their status
+****************************
+
+====================================== ========================
+ Feature Implementation status
+====================================== ========================
+Trial license with expiry date |:heavy_check_mark:|
+Link software to "physical" hardware |:heavy_check_mark:|
+Virtual machine detection In progress
+Easy license retrieval |:heavy_check_mark:|
+Manage licenses Planned
+Easy Customizable limits Planned
+Java/C# bindings Planned
+Floating/network licenses Planned
+====================================== ========================
+
+Issue a "demo" license with only expiry date.
+==============================================
+Software editors often want to release a trial license that is not linked to a specified machine, but just limit the usage in time or to some other feature (number of cpu, process memory).
+See :ref:`execution limits <Execution limits>` section.
+
+Licenses linked to "physical" hardware id
+===========================================
+Link the software to a physical hardware (a pc). In this scenario the software editor wants his software to be executed on a specific piece of hardware. We suppose the operating system is installed "bare to metal" and we're able to calculate an identifier of that hardware. This isn't always true for virtualized environments for which alternative strategies must be planned [eg. floating licenses (not yet implemented)]. See the section on [hardware identifiers](../usage/Hardware-identifiers) for a detailed discussion of the use cases.
+
+Depending on the situation there are are different kinds of hardware id that can be used. See :ref:`execution limits <Execution limits>` section.
+
+Virtual machine detection (in progress)
+==========================================
+Detect if the software is running in a virtualized environment and (optionally) forbid the execution. This is useful if software editors want to prevent the execution in virtual machines (lxc/dockers...) and be able to compute a meaningful hardware id.
+Another use case is the software is to be used only in a specific class of virtualized environments. For instance it was initially packaged as a docker image, the software editor don't want it to be "extracted" and placed elsewhere.
+
+Licenses retrieval
+=======================
+Open License Manager, when integrated into a licensed software will find its license file based on many different strategies.
+It can handle multiple licenses at the same time. See the wiki page about :ref:`license retrieval <usage/License-retrieval:License retrieval>` for details.
+
+Licensed software features (partially implemented)
+=========================================================
+A licensed software may be composed by many features (functions) each one activable independently. Licensing system tells the licensed software which features are enabled, and which features are disabled.
+
+License Management (planned)
+==================================
+It is necessary to keep track of the licenses that have been issued, of the clients, and their hardware identifier.
+A web application is planned that will provide integration with payment systems to allow licensed software customers to buy licenses.
+
+Customizable execution limits (planned)
+==========================================
+It should be easy to add and implement your own "execution limit": that is require/forbid some feature in the application execution environment.
+
+Java/C# bindings (planned)
+============================
+The application should support bindings to java language. The library has to be compiled as a .dll for use with JNI or C# integration layer. This is especially challenging on the api side.
+Since the api is public, and the library is packaged as a separate .dll/.so everybody can compile a version of it always returning LICENSE_OK easily defeating the license schema.
+
+Floating licenses (planned)
+===============================
+Limit the execution of the licensed software to a certain number of instances per license.
+This can be done in multiple ways:
+* without a central server, using broadcast or scanning the local network to find peers.
+* with a central server installed in the client's network.
+* with a central server on internet.
+Status of this implementation is tracked in `issue #4 <https://github.com/open-license-manager/open-license-manager/issues/4>`_
+
+.. _Execution Limits:
+
+Implemented/Planned Execution limits
+*************************************
+
+Open License Manager can limit execution of licensed software based on some criteria, called "execution limits".
+Depending on the execution environment some criteria may not be applicable:
+
+=============================== ==================== ==================== ============================== ====================
+feature |:arrow_down:| system-> | Windows | Linux | Linux container Virtual Machine
+ | BareToMetal | BareToMetal | (lxc/docker)
+=============================== ==================== ==================== ============================== ====================
+date |:heavy_check_mark:| |:heavy_check_mark:| |:heavy_check_mark:| |:heavy_check_mark:|
+disk label |:heavy_check_mark:| |:heavy_check_mark:| |:x:|\ :sup:`1` |:heavy_check_mark:|
+disk id |:heavy_check_mark:| |:heavy_check_mark:| |:x:|\ :sup:`1` |:heavy_check_mark:|
+ip address |:heavy_check_mark:| |:heavy_check_mark:| |:interrobang:|\ :sup:`2` |:heavy_check_mark:|
+mac address |:heavy_check_mark:| |:heavy_check_mark:| |:interrobang:|\ :sup:`2` |:heavy_check_mark:|
+cpu number Planned Planned Planned Planned
+process memory Planned Planned Planned Planned
+machine memory Planned Planned Planned Planned
+virtualization type Planned Planned Planned Planned
+concurrent execution Planned Planned Planned Planned
+licensed sw version Planned Planned Planned Planned
+=============================== ==================== ==================== ============================== ====================
+
+Date
+=========
+This is the most common limit set on a license, allow the software to expire after the defined date.
+
+Disk label/Disk id
+==============================
+It is possible to limit the execution to a computer that has a certain disk connected.
+This feature has been implemented in ``hardware identifier``.
+
+N.B.\ :sup:`1` This kind of limitation doesn't make sense in containerized environments. For an extensive discussion see the
+:ref:`hardware identifiers <usage/Hardware-identifiers:Hardware Identifiers>` section.
+
+Ip address/Mac address
+=======================
+It is possible to limit the execution to a computer that has a network card with a spefified MAC address
+(or even we can force to have a specific ip address).
+This feature has been implemented in ``hardware identifier``.
+
+N.B.\ :sup:`2` This kind of limitation,though it is supported, may not make sense in most of containerized environments.
+For an extensive discussion see the :ref:`hardware identifiers <usage/Hardware-identifiers:Hardware Identifiers>` section.
+
+Cpu Number/Machine memory
+===============================
+Allow to restrict the execution only to a machine with the specified amount of cpu or memory or less.
+This is useful in virtualized environments, to create a licensed software demo version with limited performaces or with limited scalability.
+Status of this implementation is tracked in `issue #3 <https://github.com/open-license-manager/open-license-manager/issues/3>`_
+
+Virtualization type
+==========================
+Allow the execution of the licensed software only on some type of hardware or virtualized environment
+eg. only bare to metal, only in virtual machine, only in docker.
+This feature is being implemented.
+
+Licensed software version
+===========================
+A licensed software may declare a version (eg 1.0.0). A license may span multiple releases of the software e.g. allow version 1.1.1 but not 2.0.0.
diff --git a/doc/api/extend.rst b/doc/api/extend.rst
index 8deda9a..2dbfaa7 100644
--- a/doc/api/extend.rst
+++ b/doc/api/extend.rst
@@ -1,10 +1,10 @@
#######################################
-Customizations
+Extension points
#######################################
The version 2.0 of the library comes with clear API extension and customization points.
-Custom hardware signature generator
+Tweak hardware signature generator
***************************************
You've found the provided hardware signatures don't behave well for your customers (we can test on a limited set of
diff --git a/doc/api/hardware_identifiers.rst b/doc/api/hardware_identifiers.rst
index b4c491e..4c41395 100644
--- a/doc/api/hardware_identifiers.rst
+++ b/doc/api/hardware_identifiers.rst
@@ -1,5 +1,5 @@
###############################################
-Implement your own hardware signature generator
+Customize hardware signature generators
###############################################
Customize how default strategy behaves
diff --git a/doc/conf.py b/doc/conf.py
index 4a4bf1e..327d05a 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -33,7 +33,7 @@
# ones.
extensions = ['sphinx.ext.todo',
'sphinx.ext.githubpages', 'breathe', 'recommonmark', 'sphinx_markdown_tables', 'sphinx_rtd_theme',
- 'sphinx_sitemap','sphinx.ext.autosectionlabel' ]
+ 'sphinxemoji.sphinxemoji', 'sphinx_sitemap','sphinx.ext.autosectionlabel' ]
autosectionlabel_prefix_document = True
@@ -186,5 +186,7 @@
# Sitemap plugin
html_baseurl = 'http://open-license-manager.github.io/open-license-manager'
+sphinxemoji_style = 'twemoji'
+
#html_logo = "_static/lock_32.png"
html_favicon="_static/lock_32.ico"
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
index 63b3e13..69b5e14 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -24,7 +24,7 @@
Protect the software you develop from unauthorized copies, limit the usage in time, to a specific set of
machines, or prevent the usage in virtualized environments. It is an open source license management system that helps to keep your
-software closed :smirk: . Among the other features the most notable one is: if it runs on a "real hardware"
+software closed |:smirk:| . Among the other features the most notable one is: if it runs on a "real hardware"
it can generate a signature of that hardware and report if the signature doesn't match, because for instance
the software has been copied to another pc.
@@ -60,8 +60,11 @@
* tools : Cmake(>3.6), git, make/ninja(linux)
* libraries : 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 :ref:`development/Dependencies:Dependencies` section.
-Clone the project. It has submodules, don't forget the `--recursive` option.
+For a complete list of dependencies and supported environments see the :ref:`dependencies <development/Dependencies:Dependencies>` section.
+Clone the project.
+
+.. NOTE::
+ It has submodules, don't forget the `--recursive` option.
.. code-block:: console
--
Gitblit v1.9.1