|
1 | | -Integrate cmd2 into your project |
2 | | --------------------------------- |
| 1 | +Integrate cmd2 Into Your Project |
| 2 | +================================ |
3 | 3 |
|
4 | | -[TODO - show how to use semantic versions to add the correct version string to setup.py ] |
| 4 | +Once installed, you will want to ensure that your project's dependencies |
| 5 | +include ``cmd2``. Make sure your ``setup.py`` includes the following:: |
5 | 6 |
|
6 | | -[TODO - this is probably outdated advice] |
| 7 | + install_requires=[ |
| 8 | + 'cmd2>=1,<2', |
| 9 | + ] |
7 | 10 |
|
8 | | -``cmd2`` is contained in a small number of Python files, which can be easily |
9 | | -copied into your project. *The copyright and license notice must be retained*. |
| 11 | +The ``cmd2`` project uses `Semantic Versioning <https://semver.org>`_, which |
| 12 | +means that any incompatible API changes will be release with a new major version |
| 13 | +number. We recommend that you follow the advice given by the Python Packaging |
| 14 | +User Guide related to `install_requires |
| 15 | +<https://packaging.python.org/discussions/install-requires-vs-requirements/>`_. |
| 16 | +By setting an upper bound on the allowed version, you can ensure that your |
| 17 | +project does not inadvertently get installed with an incompatible future version |
| 18 | +of ``cmd2``. |
10 | 19 |
|
11 | | -This is an option suitable for advanced Python users. You can simply include |
12 | | -the files within your project's hierarchy. If you want to modify ``cmd2``, this |
13 | | -may be a reasonable option. Though, we encourage you to use stock ``cmd2`` and |
14 | | -either composition or inheritance to achieve the same goal. |
15 | 20 |
|
16 | | -This approach will obviously NOT automatically install the required 3rd-party |
17 | | -dependencies, so you need to make sure the following Python packages are |
18 | | -installed: |
| 21 | +macOS Considerations |
| 22 | +-------------------- |
19 | 23 |
|
20 | | - * attrs |
21 | | - * colorama |
22 | | - * pyperclip |
23 | | - * wcwidth |
| 24 | +TODO need a section about how to get the right readline installed on macos |
24 | 25 |
|
25 | | -On Windows, there is an additional dependency: |
26 | 26 |
|
27 | | - * pyreadline |
| 27 | +Windows Considerations |
| 28 | +------------------------------- |
| 29 | + |
| 30 | +If you would like to use :ref:`features/completion:Completion`, and you want |
| 31 | +your application to run on Windows, you will need to ensure you install the |
| 32 | +``pyreadline`` package. Make sure to include the following in your ``setup.py``:: |
| 33 | + |
| 34 | + install_requires=[ |
| 35 | + 'cmd2>=1,<2', |
| 36 | + ":sys_platform=='win32'": ['pyreadline'], |
| 37 | + ] |
0 commit comments