151 lines
5.1 KiB
ReStructuredText
151 lines
5.1 KiB
ReStructuredText
|
|
.. |LINUXSCRIPT| replace:: https://git.ipr.univ-rennes1.fr/epsi/msspec_python3/raw/branch/devel/utils/dockerized/linux/msspec
|
|
|
|
|
|
##########################
|
|
Download and install notes
|
|
##########################
|
|
|
|
|
|
************
|
|
Installation
|
|
************
|
|
|
|
|
|
There are 2 ways to install MsSpec. You can either:
|
|
- Use a Docker image. This is, by far, the most straightforward and easy way to work with MsSpec.
|
|
- Compile your own version for your system.
|
|
|
|
|
|
|
|
1. Using a Docker image
|
|
-----------------------
|
|
|
|
You first need `Docker <https://www.docker.com>`_ to be installed on your system.
|
|
This is really straightforward. Please see the `Docker documentation
|
|
<https://docs.docker.com/engine/install/>`_ for more information depending on
|
|
your OS.
|
|
|
|
|
|
* **For Linux**,
|
|
|
|
* Download :download:`this script <../../utils/dockerized/linux/msspec>` and
|
|
make it executable (with the *chmod u+x msspec* command)
|
|
|
|
* Place it in a location known to your $PATH (or add this location to your $PATH if needed).
|
|
The *~/.local/bin* folder is a good choice.
|
|
|
|
* **For Windows**
|
|
|
|
* You need a running X server. Download and install `VcXsrv <https://sourceforge.net/projects/vcxsrv/>`_
|
|
|
|
* Install the small :download:`MsSpec frontend <../../utils/dockerized/windows/msspec_setup.exe>`
|
|
|
|
* While not necessary, it is also a good idea to use a better terminal application than the default one.
|
|
`Windows Terminal <https://www.microsoft.com/fr-fr/p/windows-terminal/9n0dx20hk701#activetab=pivot:overviewtab>`_
|
|
may be a good choice.
|
|
|
|
* **For Mac**
|
|
|
|
* *To be documented*
|
|
|
|
|
|
Open a terminal in Linux, or a powershell in Windows and type in::
|
|
|
|
msspec
|
|
|
|
The first time you run the command, it will download the msspec image (it may takes several minutes or half an hour
|
|
depending on your internet connexion).
|
|
The command will automatically create a new container and start it.
|
|
As the command was entered without any argument on the command-line, the help message should be printed on the screen
|
|
|
|
.. code-block:: text
|
|
|
|
Usage: 1) msspec -p [PYTHON OPTIONS] SCRIPT [ARGUMENTS...]
|
|
2) msspec [-l FILE | -i | -h]
|
|
3) msspec [bash | reset]
|
|
|
|
Form (1) is used to launch a script
|
|
Form (2) is used to load a hdf5 data file
|
|
Form (3) is used to control the Docker container/image.
|
|
|
|
List of possible options:
|
|
-p Pass every arguments after this option to the msspec
|
|
virtual environment Python interpreter.
|
|
-i Run the interactive Python interpreter within msspec
|
|
virtual environment.
|
|
-l Load and display a *.hdf5 data file in a graphical
|
|
window.
|
|
-v Print the version.
|
|
-h Show this help message.
|
|
|
|
bash This command starts an interactive bash shell in the
|
|
MsSpec container.
|
|
reset This command removes the MsSpec container (but not the
|
|
image). Changes made in the container will be lost and
|
|
any new call to msspec will recreate a new fresh container.
|
|
|
|
|
|
2. Compile your own version
|
|
---------------------------
|
|
|
|
To install MsSpec this way, follow the instructions `here <https://git.ipr.univ-rennes1.fr/epsi/msspec_python3>`_
|
|
|
|
|
|
***************************
|
|
Running your Python scripts
|
|
***************************
|
|
|
|
You can run your MsSpec Python scripts (e.g. *my_script.py*) by typing in::
|
|
|
|
msspec -p my_script.py
|
|
|
|
This command is equivalent to activating the Python virtual environment MsSpec is intsalled in
|
|
and to run the Python interpreter of that environment (everything that follows the -p option is
|
|
passed to the python command).
|
|
|
|
You can also launch the Interactive Python (iPython) of MsSpec::
|
|
|
|
msspec -i
|
|
|
|
Inside this interactive session, you can run a script with the command::
|
|
|
|
%run my_script.py
|
|
|
|
You can interact with your filesystem with the classical *cd*, *ls*, *cp*, *rm*... commands.
|
|
and you can edit your script with::
|
|
|
|
%ed my_script.py
|
|
|
|
|
|
.. warning::
|
|
|
|
**If using the Docker image of MsSpec in Linux**, your home folder on the host machine is bind mounted
|
|
in the same location in the container and your UID and GID are also set so that creating files within
|
|
your home file hierarchy is totally transparent.
|
|
|
|
**If using the Docker image of MsSpec in Windows**, the drive containing your "My Documents" folder on the
|
|
host machine is bind mounted on the container at the root of the filesystem. For example, if your
|
|
"My documents" folder on Windows are in 'D:\\Home\\Bob\\MyDocuments', it will be available in the container as
|
|
'/D/Home/Bob/MyDocuments'. It has two consequences:
|
|
|
|
#. The msspec command will fail if running on another drive than the one where is located "My Documents"
|
|
|
|
#. You have to specify filenames with the Unix slashes. For example if you want to run the script located
|
|
in *.\\results\\my_script.py*, you will have to enter *msspec -p ./results/my_script.py*
|
|
|
|
|
|
**************
|
|
Uninstallation
|
|
**************
|
|
|
|
* **Under Linux**, type in::
|
|
|
|
msspec -u
|
|
|
|
* **Under Windows**, simply `uninstall the application from the Settings page
|
|
<https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-10-4b55f974-2cc6-2d2b-d092-5905080eaf98>`_.
|
|
A command window will pop-up and you will have to answer 'y' to remove MsSpec.
|
|
|
|
* **Under Mac OS**, *to be documented.*
|