Skip to content

Commit

Permalink
doc: improve doc for conda use and add warning to recomment its use (#…
Browse files Browse the repository at this point in the history 
…2722)
  • Loading branch information
@marcelotduarte
marcelotduarte authored Dec 10, 2024
1 parent 102296c commit 40a6e26
Show file tree
Hide file tree
Showing 4 changed files with 88 additions and 40 deletions.
13 changes: 11 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,11 @@ itself works on.

# Installation

In a virtual environment, install by issuing the command:
Choose the Python package manager according to your system. See how the
installation works with the most common ones, which are pip and conda.

To install the latest version of `cx_Freeze` using `pip` into a
virtual environment:
```
pip install --upgrade cx_Freeze
```
Expand All @@ -30,9 +33,15 @@ pip uninstall cx_Freeze
pip install --extra-index-url https://test.pypi.org/simple/ cx_Freeze --pre --no-cache
```

Installing cx_freeze from the conda-forge channel can be achieved with the
command:
```
conda install conda-forge::cx_freeze
```

Please check the
[installation](https://cx-freeze.readthedocs.io/en/latest/installation.html)
for more information and how to install in other environments.
for more information.

# Documentation

Expand Down
45 changes: 37 additions & 8 deletions cx_Freeze/freezer.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,18 @@

from setuptools import Distribution

from cx_Freeze._compat import BUILD_EXE_DIR, IS_MACOS, IS_MINGW, IS_WINDOWS
from cx_Freeze._compat import (
BUILD_EXE_DIR,
IS_CONDA,
IS_MACOS,
IS_MINGW,
IS_WINDOWS,
)
from cx_Freeze.common import get_resource_file_path, process_path_specs
from cx_Freeze.exception import FileError, OptionError
from cx_Freeze.executable import Executable
from cx_Freeze.finder import ModuleFinder
from cx_Freeze.module import ConstantsModule, Module
from cx_Freeze.module import ConstantsModule, DistributionCache, Module
from cx_Freeze.parser import ELFParser, Parser, PEParser

if TYPE_CHECKING:
Expand All @@ -42,6 +48,27 @@

__all__ = ["ConstantsModule", "Executable", "Freezer"]

WARNING_PIP_CX_FREEZE_IN_CONDA_PYTHON = """WARNING:
It is not recommended to use cx_Freeze installed from pip with conda \
python.
To install cx_Freeze as conda package (cx_freeze):
pip uninstall cx_Freeze
conda install conda-forge::cx_freeze
To fix this issue, refer to the documentation:
\
https://cx-freeze.readthedocs.io/en/stable/installation.html#conda-forge
"""

WARNING_USING_PYTHON_FROM_MS_STORE = """WARNING:
Because of restrictions on Microsoft Store apps, Python scripts may not \
have full write access to built executable.
You will need to install the full installer.
"""


class Freezer:
"""Freezer base class."""
Expand Down Expand Up @@ -141,6 +168,7 @@ def __init__(
self.files_copied: set[Path] = set()
self.modules_copied: list[Module] = []
self.finder: ModuleFinder = self._get_module_finder()
self._check_installation()

@property
def target_dir(self) -> Path:
Expand Down Expand Up @@ -176,6 +204,12 @@ def _add_resources(self, exe: Executable) -> None:
target_icon = self.target_dir / exe.icon.name
self._copy_file(exe.icon, target_icon, copy_dependent_files=False)

def _check_installation(self) -> None:
if IS_CONDA:
dist = DistributionCache(self.finder.cache_path, "cx_Freeze")
if dist.installer == "pip":
print(WARNING_PIP_CX_FREEZE_IN_CONDA_PYTHON, file=sys.stderr)

def _copy_file(
self,
source: Path,
Expand Down Expand Up @@ -872,12 +906,7 @@ def _add_resources(self, exe: Executable) -> None:
if "\\WindowsApps\\" in sys.base_prefix:
if self.silent < 3:
print("WARNING:", exc)
print(
"WARNING: Because of restrictions on "
"Microsoft Store apps, Python scripts may not "
"have full write access to built executable. "
"You will need to install the full installer."
)
print(WARNING_USING_PYTHON_FROM_MS_STORE)
else:
raise

Expand Down
39 changes: 23 additions & 16 deletions doc/src/development/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,23 +22,23 @@ You can use ``git`` to clone the repository:

.. code-block:: console
git clone https://github.com/marcelotduarte/cx_Freeze
cd cx_Freeze
make install
git clone https://github.com/marcelotduarte/cx_Freeze
cd cx_Freeze
make install
If you don't have make installed, run:

.. code-block:: console
python -m pip install --upgrade pip
pip install -e .[dev,doc]
pre-commit install --install-hooks --overwrite -t pre-commit
python -m pip install --upgrade pip
pip install -e .[dev,doc]
pre-commit install --install-hooks --overwrite -t pre-commit
.. note::

#. It is recommended to use a virtual environment.
#. Please check the requirements for python on your system
(see :doc:`../installation`).
(see :ref:`python_requirements`).

Building redistributable binary wheels
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -59,26 +59,26 @@ To reach this, cx_Freeze's binary wheels is built using :pypi:`cibuildwheel`.

.. code-block:: console
pip install --upgrade cibuildwheel
pip install --upgrade cibuildwheel
For instance, in a Linux environment, Python 3.10, to build locally, run:

.. code-block:: console
cibuildwheel --only cp310-manylinux_x86_64
cibuildwheel --only cp310-manylinux_x86_64
To run a Linux build on your development machine, Docker or Podman should be
installed. To use podman:

.. code-block:: console
CIBW_CONTAINER_ENGINE=podman cibuildwheel --only cp310-manylinux_x86_64
CIBW_CONTAINER_ENGINE=podman cibuildwheel --only cp310-manylinux_x86_64
Using macOS:

.. code-block:: console
cibuildwheel --only cp310-macosx_universal2
cibuildwheel --only cp310-macosx_universal2
.. note::

Expand All @@ -100,14 +100,14 @@ written in reStructuredText. To build it locally, run:

.. code-block:: console
make html
make html
The built documentation can be found in the ``build/doc/html`` folder and may
be viewed by opening ``index.html`` within that folder.

.. code-block:: console
make htmltest
make htmltest
Conda-forge
-----------
Expand All @@ -127,10 +127,17 @@ An example for Linux:

.. code-block:: console
conda create -n cx311conda -c conda-forge python=3.11 -y
git clone https://github.com/marcelotduarte/cx_Freeze
cd cx_Freeze
conda create -n cx311conda -c conda-forge python=3.11 c-compiler -y
conda activate cx311conda
conda install -c conda-forge c-compiler patchelf -y
pip install git+https://github.com/marcelotduarte/cx_Freeze@develop
conda install -c conda-forge patchelf -y
conda install -c conda-forge --file=requirements-dev.txt
pre-commit install --install-hooks --overwrite -t pre-commit
pip install -e. --no-deps --no-build-isolation
.. note::
``pip`` should be used in conda only in development mode.

Contributing
-------------
Expand Down
31 changes: 17 additions & 14 deletions doc/src/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,14 @@
Installation
============

Choose the Python package manager according to your system. See how the
installation works with the most common ones, which are pip and conda.

Pip
---

You should install the latest version of :pypi:`cx_Freeze` using :pypi:`pip`:
To install the latest version of :pypi:`cx_Freeze` using :pypi:`pip` into a
virtual environment:

.. code-block:: console
Expand All @@ -15,38 +19,37 @@ You should install the latest version of :pypi:`cx_Freeze` using :pypi:`pip`:
The recommended way to use cx_Freeze is in a
:pythondocs:`virtual environment <library/venv.html>`.
If you're unfamiliar with Python virtual environments, check out the
:packaging:`packaging user guide <guides/installing-using-pip-and-virtual-environments>`.
:packaging:`packaging user guide
<guides/installing-using-pip-and-virtual-environments>`.

.. important::
Please note that some operating systems might be equipped with the python3
and pip3 commands instead of python and pip (but they should be equivalent).

Pipenv
------

Using pipenv, install or update by issuing one of the following commands:

.. code-block:: console
pipenv install cx_Freeze
pipenv update cx_Freeze
Conda-forge
-----------

Directly from the conda-forge channel:
Installing cx_freeze from the conda-forge channel can be achieved with the
command:

.. code-block:: console
conda install conda-forge::cx_freeze
.. note::
It is not recommended to use ``pip`` in conda environment. See why in
`Using Pip in a Conda Environment
<https://www.anaconda.com/blog/using-pip-in-a-conda-environment>`_.

.. seealso:: `cx_freeze-feedstock
<https://github.com/conda-forge/cx_freeze-feedstock#installing-cx_freeze>`_.

.. _python_requirements:

Python requirements
-------------------

Python requirements are installed automatically by pip, pipenv, or conda.
Python requirements are installed automatically by pip or conda.

.. code-block:: console
Expand Down

0 comments on commit 40a6e26

Please sign in to comment.