beastie/old-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restart repo

Browse Source
This commit is contained in:
Jérémie SALVI
2023-12-30 22:30:42 +01:00
commit 1c4278a3d8
37 changed files with 3019 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

445
LICENSE.md Normal file
View File

@@ -0,0 +1,445 @@
# GNU Free Documentation License
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation,
Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
#### 0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals; it
can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
#### 1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The "Document", below, refers
to any such manual or work. Any member of the public is a licensee,
and is addressed as "you". You accept the license if you copy, modify
or distribute the work in a way requiring permission under copyright
law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject. (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may be
at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies of
the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
#### 2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no
other conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
#### 3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify you
as the publisher of these copies. The front cover must present the
full title with all words of the title equally prominent and visible.
You may add other material on the covers in addition. Copying with
changes limited to the covers, as long as they preserve the title of
the Document and satisfy these conditions, can be treated as verbatim
copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to
give them a chance to provide you with an updated version of the
Document.
#### 4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
- A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of previous
versions (which should, if there were any, be listed in the
History section of the Document). You may use the same title as a
previous version if the original publisher of that version
gives permission.
- B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in the
Modified Version, together with at least five of the principal
authors of the Document (all of its principal authors, if it has
fewer than five), unless they release you from this requirement.
- C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified Version
under the terms of this License, in the form shown in the
Addendum below.
- G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on the
Title Page. If there is no section Entitled "History" in the
Document, create one stating the title, year, authors, and
publisher of the Document as given on its Title Page, then add an
item describing the Modified Version as stated in the
previous sentence.
- J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for previous
versions it was based on. These may be placed in the "History"
section. You may omit a network location for a work that was
published at least four years before the Document itself, or if
the original publisher of the version it refers to
gives permission.
- K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document, unaltered
in their text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
- M. Delete any section Entitled "Endorsements". Such a section may
not be included in the Modified Version.
- N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant Section.
- O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties—for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
#### 5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications". You must delete all sections
Entitled "Endorsements".
#### 6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the rules
of this License for verbatim copying of each of the documents in all
other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert a
copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.
#### 7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
#### 8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
#### 9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt otherwise
to copy, modify, sublicense, or distribute it is void, and will
automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
#### 10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the
GNU Free Documentation License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in
detail to address new problems or concerns. See
<https://www.gnu.org/licenses/>.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation. If the Document specifies
that a proxy can decide which future versions of this License can be
used, that proxy's public statement of acceptance of a version
permanently authorizes you to choose that version for the Document.
#### 11. RELICENSING
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server. A
"Massive Multiauthor Collaboration" (or "MMC") contained in the site
means any set of copyrightable works thus published on the MMC site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or in
part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
### ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with … Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

16
README.md Normal file
View File

@@ -0,0 +1,16 @@
Documentation Unix Your Brain
=============================
La Documentation Unix Your Brain est générée par l'outil [Sphinx](https://www.sphinx-doc.org/en/master/#). [Le dépot Git de cette documentation](https://git.unixyourbrain.org/doc.git/) ne contient que les sources de la documentation.
Pour en savoir plus sur le fonctionnement de sphinx, vous trouverez toute la documentation nécessaire sur leur [site officiel](https://www.sphinx-doc.org/en/master/#).
Pour l'installation et la configuration de sphinx sous debian 11, j'ai créé un tuto mémo sur la documentation Unix Your Brain à [l'adresse suivante](https://docs.unixyourbrain.org/index.html)
Licence
-------
Sphinx est distrubué sous [licence BSD](https://github.com/sphinx-doc/sphinx/blob/master/LICENSE).
Sauf indication contraire, chaque document est distribué sous Licence [GNU FDLv3](https://www.gnu.org/licenses/fdl-1.3.html). Vous trouverez
une copie de la licence dans le fichier LICENSE.md ou dans la section GNU Free Documentation License.

21
_static/custom.css Normal file
View File

@@ -0,0 +1,21 @@
/* Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License". */
.rst-content pre.literal-block, .rst-content div[class^="highlight"] {
background: #282c34;
color: #abb2bf;
border: 1px solid #333842;
}
.rst-content div.highlight span.linenos {
border-right: 1px solid #333842;
}
.rst-content div[class^="highlight"] pre .hll {
background-color: #13533b;
}

41
conf.py Normal file
View File

@@ -0,0 +1,41 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'Documentation Unix Your Brain'
copyright = '2023, Jeremie Salvi <docs@unixyourbrain.org>. This documentation is published under GNU FDL License'
author = 'Jeremie Salvi <docs@unixyourbrain.org>'
release = '0.1'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
# 'sphinxemoji.sphinxemoji',
'myst_parser'
]
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}
templates_path = ['_templates']
exclude_patterns = []
root_doc = 'index'
language = 'fr'
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_rtd_theme'
# html_static_path = ['_static']
# html_css_files = [
# 'custom.css',
# ]

8
docs.code-workspace Normal file
View File

@@ -0,0 +1,8 @@
{
"folders": [
{
"path": "."
}
],
"settings": {}
}

24
esp32/index.rst Normal file
View File

@@ -0,0 +1,24 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Programmation d'un ESP32
========================
Ici je vais poser toutes mes astuces pour la programmation et le débugage d'un ESP32,
ainsi qu'une présentation de mes projets. Je tiens à noter que je suis passé sous
ArchLinux, l'installation et la configuration va donc légèrement changer par rapport à Debian.
.. toctree::
:maxdepth: 2
installation.rst
vscodium_integration.rst
qemu_emulation.rst
qemu_ethernet.rst

163
esp32/installation.rst Normal file
View File

@@ -0,0 +1,163 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Installation de l'environnement sous ArchLinux
==============================================
Introduction
------------
Tout d'abord je tiens à vous rassurer, cela doit fonctionner sur la majorité des distributions.
Je vais utiliser vscodium (fork de visual studio code sans la télémétrie microsoft),
un framework basé sur electron, donc compatible multi OS et multi distributions.
L'emulateur basé sur QEMU sera compilé à la main, donc ça devrait passer sur n'importe quel linux 😊.
.. warning:: Je suis passé en root pour ne pas m'encombrer avec ``sudo``, pensez y si nécessaire
Pour plus d'infos en général, allez faire un tour sur `La documentation officielle de l'esp 32 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/>`_
Installation de vscodium
------------------------
Vscodium n'est pas disponible dans les paquets officiels ArchLinux, il faut donc aller sur les ArchLinux User Repositories (AUR.)
`Dépot AUR des binaires vscodium <https://aur.archlinux.org/packages/vscodium-bin>`_
.. code-block:: bash
:linenos:
:caption: installation de vscodium
cd /opt
git clone https://aur.archlinux.org/vscodium-bin.git
cd vscodium-bin/
makepkg
pacman -U vscodium-bin-1.72.2.22289-1-x86_64.pkg.tar.zst
.. warning:: Si vous êtes en root pour programmer, il faut utiliser les arguments suivants pour
lancer vscodium : ``codium --no-sandbox --user-data-dir ~/.config/vscodium``
Pour le confort de développement, nous allons installer une extension pour améliorer
l'autocompletion en C/C++. Elle n'est pas disponible sur le marketplace vscodium, il faut l'installer
manuellement. On la télécharge `ici <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_.
On l'installe depuis le menu des extensions comme ci dessous.
.. image:: ../images/esp32/ms_cpp_extension.png
:width: 400
Nous allons aussi utiliser l'extension native debug pour l'intégration du debugeur.
Elle se trouve dans le store. Pour l'utilistation, on verra ça dans la partie
`création d'un environnement vscodium </esp32/vscode_integration.html#configurer-le-debugeur>`_.
.. image:: ../images/esp32/native_debug_extension.png
:width: 400
Installation des prérequis pour l'esp-idf (Espressif IoT Development Framework)
-------------------------------------------------------------------------------
La commande est directement fournie dans la documentation, il suffit de la copier coller :
.. code-block:: bash
pacman -S --needed gcc git make flex bison gperf python cmake ninja dfu-util ccache libusb
Installation et configuration de l'esp-idf
------------------------------------------
Dans un premier temps, on récupère les dépots :
.. code-block:: bash
:linenos:
mkdir -p /opt/esp
cd /opt/esp
git clone --recursive https://github.com/espressif/esp-idf.git
Il faut ensuite installer les outils. Par defaut ils sont installés dans ``$HOME/.espressif``.
On peut changer cet emplacement grâce à la variable d'environnement ``IDF_TOOLS_PATH``.
.. code-block:: bash
:linenos:
export IDF_TOOLS_PATH=/opt/esp/esp-idf/.espressif
cd esp-idf
./install.sh esp32
L'environnement utilise un paquets d'outils, il est dur de mémoriser tout
les chemins et les variables d'environnement. Heureusement on nous fournit aussi un sctipt
qui rend tout ça accessible depuis la console. Pour ça il faut le charger :
.. code-block:: bash
. /opt/esp/esp-idf/export.sh
Comme il faut l'appeller dans chaque nouveau terminal, on
se créer un alias pour faciliter l'accès :
.. code-block:: bash
alias esp_idf_import=". /opt/esp/esp-idf/export.sh"
On colle cette ligne dans notre .bashrc ou notre .profile. Pour vérifier qu'on
a bien tout importé, on tappe la commande env, et on devrait avoir les infos
suivantes :
.. code-block:: bash
:linenos:
env
>> ESP_IDF_VERSION="5.1"
>> ESP_ROM_ELF_DIR="/opt/esp/esp-idf/.espressif/tools/esp-rom-elfs/20220823/"
>> IDF_DEACTIVATE_FILE_PATH="/tmp/tmpxj9n6nndidf_46523"
>> IDF_PATH="/opt/esp/esp-idf"
>> IDF_PYTHON_ENV_PATH="/opt/esp/esp-idf/.espressif/python_env/idf5.1_py3.10_env"
>> IDF_TOOLS_EXPORT_CMD="/opt/esp/esp-idf/export.sh"
>> IDF_TOOLS_INSTALL_CMD="/opt/esp/esp-idf/install.sh"
>> IDF_TOOLS_PATH="/opt/esp/esp-idf/.espressif"
>> OPENOCD_SCRIPTS="/opt/esp/esp-idf/.espressif/tools/openocd-esp32/v0.11.0-esp32-20221026/openocd-esp32/share/openocd/scripts"
>> PATH="/opt/esp/esp-idf/components/esptool_py/esptool:/opt/esp/esp-idf/components/espcoredump:/opt/esp/esp-idf/components/partition_table:/opt/esp/esp-idf/components/app_update:/opt/esp/esp-idf/.espressif/tools/xtensa-esp-elf-gdb/12.1_20221002/xtensa-esp-elf-gdb/bin:/opt/esp/esp-idf/.espressif/tools/xtensa-esp32-elf/esp-2022r1-11.2.0/xtensa-esp32-elf/bin:/opt/esp/esp-idf/.espressif/tools/esp32ulp-elf/2.35_20220830/esp32ulp-elf/bin:/opt/esp/esp-idf/.espressif/tools/openocd-esp32/v0.11.0-esp32-20221026/openocd-esp32/bin:/opt/esp/esp-idf/.espressif/python_env/idf5.1_py3.10_env/bin:/opt/esp/esp-idf/tools:/usr/local/sbin:/usr/local/bin:/usr/bin"
Si l'on à pas les chemins ``/opt/esp/esp-idf`` dans le path et les variables d'environnement ``IDF_``, les outils fournis
dans l'ESP-IDF ne fonctionneront tout simplement pas.
Compilation de qemu-system-xtensa patché pour les esp32
-------------------------------------------------------
Espressif, l'entreprise qui concoit les ESP32, nous fournit un fork de QEMU modifié pour emmuler celui ci.
On le trouve à l'addresse suivante : `GitHub du fork QEMU <https://github.com/espressif/qemu>`_.
Toute la procédure est expliquée ici : `Wiki du dépot <https://github.com/espressif/qemu>`_.
Je ne vais pas tout réexpliquer ici, ce qu'il faut savoir c'est que nous ne voulons pas
recompiler tout qemu, juste le binaire qemu-system-xtensa modifié pour esp32. Je vais donc
refaire la compilation en désactivant un maximum de fonctionnalités inutiles. On trouve la
liste des fonctionnalités dans le fichier ``configure`` du dépot.
.. code-block:: bash
:linenos:
:caption: compilation de QEMU pour esp32
#!/bin/bash
cd /opt
git clone https://github.com/espressif/qemu.git
cd qemu
./configure --target-list=xtensa-softmmu \
--enable-gcrypt \
--enable-debug --enable-sanitizers \
--disable-strip --disable-user \
--disable-capstone --disable-vnc \
--disable-sdl --disable-gtk \
--disable-opengl --disable-vfio-user-server
ninja -C build

307
esp32/qemu_emulation.rst Normal file
View File

@@ -0,0 +1,307 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Premiers tests et emulation QEMU
================================
Espressif fournit une version de QEMU modifiée pour tester du code. Cela peut avoir
plusieurs avantages :
* Commencer à coder sans attendre la livraison de notre ESP.
* Tester du code plus rapidement sans avoir à flasher notre ESP.
* Coder toute la partie web en local sur notre machine.
* Attacher un debugeur, utiliser des berakpoints, et débuger plus facilement.
Pour cela, nous reprendront le `code de la partie précédente </esp32/vscodium_integration.html#configuration-de-l-extension-c-c>`_.
Première Execution
------------------
On reprend le projet vu dans l'intégration vscodium. Pout lancer QEMU il nous faut construire la mémonire
flash pour la donner à QEMU qu'elle puisse démarrer dessus.
.. code-block:: bash
python /opt/esp/esp-idf/components/esptool_py/esptool/esptool.py \
--chip esp32 merge_bin --output flash_img.bin \
--fill-flash-size 4MB --flash_mode dio --flash_size keep --flash_freq 40m \
0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/new_project.bin
Voilà, il ne nous reste plus qu'à lancer QEMU à partir de cette image !
Emulation du système dans une machine QEMU
------------------------------------------
Il suffit maintenant de lancer notre machine QEMU à partir de la flash que l'on vient de créer :
.. code-block:: bash
/opt/qemu/build/qemu-system-xtensa -nographic -machine esp32 \
-drive file=flash_img.bin,if=mtd,format=raw
Et voilà, on emule la machine et on à la sortie série qui s'affiche. Pour quitter QEMU, on utilise
``Ctrl-A x``
Flasher ou monitorer en emulant un port série
---------------------------------------------
Cela ne va pas beaucoup nous servir, puisqu'il suffit de relancer qemu avec notre nouvelle
image du flash, mais il faut savoir que c'est possible en emulant les GPIO de notre ESP.
on à deux configurations :
* ``-global driver=esp32.gpio,property=strap_mode,value=0x12`` pour monitorer la sortie.
* ``-global driver=esp32.gpio,property=strap_mode,value=0xf`` pour flasher la carte.
Attention, le port série ne peut pas recevoir deux connexions en même temps, il faut donc
couper le moniteur pour flasher et vice versa.
Monitorer QEMU
~~~~~~~~~~~~~~
On commence par lancer QEMU avec le port série en mode monitor.
.. code-block:: bash
/opt/qemu/build/qemu-system-xtensa -nographic -machine esp32 \
-drive file=flash_img.bin,if=mtd,format=raw \
-global driver=esp32.gpio,property=strap_mode,value=0x12 \
-serial tcp::5555,server,nowait
On lance ensuite le moniteur
.. code-block:: bash
idf.py --port socket://localhost:5555 monitor
Flasher QEMU
~~~~~~~~~~~~
On commence par lancer QEMU avec le port série en mode flash.
.. code-block:: bash
/opt/qemu/build/qemu-system-xtensa -nographic -machine esp32 \
-drive file=flash_img.bin,if=mtd,format=raw \
-global driver=esp32.gpio,property=strap_mode,value=0xf \
-serial tcp::5555,server,nowait \
On flash ensuite notre machine
.. code-block:: bash
idf.py --port socket://localhost:5555 flash
Debuger grâce de QEMU avec gdb
------------------------------
Pour attacher GDB, on lance la commande avec ``-s -S`` qui va nous ouvrir un socket tcp sur le port 1234.
pour changer de port, on utilise : ``-gdb tcp::1235``
.. code-block:: bash
/opt/qemu/build/qemu-system-xtensa -nographic -machine esp32 \
-drive file=flash_img.bin,if=mtd,format=raw \
-gdb tcp:localhost:1235 -S
On peut ensuite lancer le debugeur fourni avec l'API, mettre des breakpoints, etc.
.. code-block:: bash
:linenos:
/root/.espressif/tools/xtensa-esp-elf-gdb/12.1_20221002/xtensa-esp-elf-gdb/bin/xtensa-esp32-elf-gdb build/main.elf
(gdb) b app_main
# >> Breakpoint 1 at 0x400d5170: file /root/test/sample_project/main/main.c, line 7.
(gdb) target remote :1235
# >> Remote debugging using :1235
# >> 0x40000400 in ?? ()
(gdb) c
# Continuing.
# Thread 1 hit Breakpoint 1, app_main () at /root/test/sample_project/main/main.c:7
(gdb) n
# >> 8 int count = 0;
(gdb) n
# >> 11 ESP_LOGI("FIRST TRY", "Test loop pass n° %d", count++);
(gdb) b
# >> Breakpoint 2 at 0x400d5175: file /root/test/sample_project/main/main.c, line 11.
(gdb) c
# >> Continuing.
# >> Thread 1 hit Breakpoint 2, app_main () at /root/test/sample_project/main/main.c:11
# >> 11 ESP_LOGI("FIRST TRY", "Test loop pass n° %d", count++);
(gdb) c
# >> Continuing.
# >> Thread 1 hit Breakpoint 2, app_main () at /root/test/sample_project/main/main.c:11
# >> 11 ESP_LOGI("FIRST TRY", "Test loop pass n° %d", count++);
(gdb) print count
# >> $1 = 2
(gdb) set count=100
(gdb) c
# >> Continuing.
# >> Thread 1 hit Breakpoint 2, app_main () at /root/test/sample_project/main/main.c:11
# >> 11 ESP_LOGI("FIRST TRY", "Test loop pass n° %d", count++);
(gdb) quit
.. image:: ../images/esp32/QEMU_gdb_example.png
:width: 400
Voilà. On va voir plus tard comment configurer cela dans vscodium
Intégration dans vscodium
-------------------------
On arrive ici à ce qui pour moi donne une vraie utilité à configurer un environnement QEMU.
On va pouvoir à partir de vscode gérer nos breakpoint, naviguer dans le code, avoir sous
les yeux les variables et les call stack, etc.
Création des tâches
~~~~~~~~~~~~~~~~~~~
Je ne réexplique pas tout, on à déjà vu le fonctionnement dans la
`partie précédente </esp32/vscodium_integration.html#configurer-des-taches>`_
On rajoute quelques fonctions suivantes à notre script et on ajoute les tâches pour
lancer le débug et l'execution avec QEMU.
.. code-block:: bash
:linenos:
function kill_qemu {
for i in $(ps -elf | grep 'qemu-system-xtensa' | awk '{print $4}')
do
echo "found process $i"
kill $i
done
}
function qemu_execute {
kill_qemu
python /opt/esp/esp-idf/components/esptool_py/esptool/esptool.py \
--chip esp32 merge_bin --output flash_img.bin \
--fill-flash-size 4MB --flash_mode dio --flash_size keep --flash_freq 40m \
0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin \
0x10000 build/new_project.bin
/opt/qemu/build/qemu-system-xtensa -nographic -machine esp32 \
-drive file=flash_img.bin,if=mtd,format=raw
exit 0
}
function qemu_debug {
kill_qemu
python /opt/esp/esp-idf/components/esptool_py/esptool/esptool.py \
--chip esp32 merge_bin --output flash_img.bin \
--fill-flash-size 4MB --flash_mode dio --flash_size keep --flash_freq 40m \
0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin \
0x10000 build/new_project.bin
/opt/qemu/build/qemu-system-xtensa -nographic -machine esp32 \
-drive file=flash_img.bin,if=mtd,format=raw -s -S
exit 0
}
#######################
# Main
#######################
case $1 in
kill_idf)
echo "Killing all idf process"
kill_idf
;;
kill_qemu)
echo "Killing all idf process"
kill_qemu
;;
qemu_execute)
echo "Execute with QEMU"
qemu_execute
;;
qemu_debug)
echo "Debug with QEMU"
qemu_debug
;;
*)
echo "Missing args"
exit 1
;;
esac
.. code-block:: json
:linenos:
{
"label": "Execute with QEMU",
"type": "shell",
"command": "${workspaceFolder}/.scripts/tasks.sh",
"args": [
"qemu_execute"
],
"presentation": {
"reveal": "always",
"panel": "new",
"close": true
},
"problemMatcher": []
},
{
"label": "Debug with QEMU",
"type": "shell",
"command": "${workspaceFolder}/.scripts/tasks.sh",
"args": [
"qemu_debug"
],
"presentation": {
"reveal": "always",
"panel": "new",
"close": true
},
"problemMatcher": []
},
Intégration de gdb dans vscodium
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pour cela, il faut éditer le fichier ``.vscode/launch.json``
.. code-block:: json
:linenos:
{
"configurations": [
{
"type": "gdb",
"gdbpath": "/root/.espressif/tools/xtensa-esp-elf-gdb/12.1_20221002/xtensa-esp-elf-gdb/bin/xtensa-esp32-elf-gdb",
"postDebugTask": "kill QEMU process",
"request": "attach",
"name": "Attach to QEMU",
"executable": "${workspaceFolder}/build/main.elf",
"target": ":1234",
"remote": true,
"cwd": "${workspaceRoot}",
"valuesFormatting": "parseText"
}
]
}
Voilà, on n'a plus qu'à lancer la tâche ``Debug with QEMU`` et de lancer le débugeur.
.. image:: ../images/esp32/debug.png
:width: 600
On se retrouve avec les breakpoints, les call stacks, les variables et la sortie tous affichés sans notre
environnement de travail 💪.
Prochaine étape
---------------
Les interactions avec l'électronique devant être faites avec un vrai ESP, le développement
sous QEMU ne nous sert à rien si on ne peut pas coder la partie réseau et communications depuis le PC.
Prochaine étape donc, faire tourner l'emulation avec une interface réseau pour coder notre serveur web
embarqué.

203
esp32/qemu_ethernet.rst Normal file
View File

@@ -0,0 +1,203 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Interface ethernet avec QEMU
============================
Y a pas à dire, j'ai bien galéré pour cette partie 😅. Bon, faut dire q'il y avait des choses qui
ne fonctionnent pas. J'y refient à la fin de cette section.
Après pas mal de tatonnements entre la doc et les exemples fournis par espressif, j'ai finalement
réussi à interagir entre firefox et la machine QEMU. Il y a plusieures choses à bien comprendre
dans la façon dont fonctionne l'IDF, notament comment sont gérées les
`différentes couches du modèle OSI <https://fr.wikipedia.org/wiki/Mod%C3%A8le_OSI>`_.
Principes
---------
dans l'ESP, il y à trois étapes principales pour le réseau :
#. La partie physique (couches physique + mac),
#. La partie network (couches network + transport),
#. La partie link entre physique et network.
La partie physique
~~~~~~~~~~~~~~~~~~
C'est la couche physique plus la couche mac. On la configure, on la démare, et ensuite on
la link à la partie network. Côté wifi, comme le driver de la carte est toujours le même,
on à la fonction ``esp_netif_create_default_wifi_sta()`` qui gère tout, elle créer tout.
Elle gère la partie physique, la link à la partie network, et nous retourne un handle de la
partie network.
Pour l'ethernet, c'est différent, comme plusieurs extensions ethernet sont disponible pour
l'esp32, il y a plusieurs drivers disponibles, il nous faut donc choisir le bon, et configurer ça à la main.
Dans notre cas, pour QEMU, le driver à utiliser est le driver openeth. (`cf wiki qemu <https://github.com/espressif/qemu/wiki>`_)
La configuration de la partie physique se fait à l'aide des fonctions suivantes :
.. code-block:: cpp
:linenos:
// Pysical layer configuration
eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG();
phy_config.phy_addr = -1;
phy_config.reset_gpio_num = -1;
phy_config.autonego_timeout_ms = 4000;
s_phy = esp_eth_phy_new_dp83848(&phy_config);
// Data link layer configuration
eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG();
mac_config.rx_task_stack_size = 4096;
mac_config.rx_task_prio = 20;
s_mac = esp_eth_mac_new_openeth(&mac_config);
// Install Ethernet driver
esp_eth_config_t config = ETH_DEFAULT_CONFIG(s_mac, s_phy);
esp_eth_driver_install(&config, &esp_eth_handle);
La partie network
~~~~~~~~~~~~~~~~~
Can cette partie, on gère la couche ip et la couche transport (TCP/UDP/ICMP). Espressif nous donne pour ça tout un tas
de fonctions, qui sont un wrapper des librairies opensource `lwIP <https://fr.wikipedia.org/wiki/LwIP>`_ (lightweight IP).
Elle nous permet d'initialiser ces couches, de gérer l'attribution de l'adressage ip (statique ou DHCP.)
Cette couche s'implémente avec les fonctions suivantes :
.. code-block:: cpp
:linenos:
// Initialize TCP/IP layers
esp_netif_init();
esp_event_loop_create_default();
esp_netif_config_t esp_netif_config = ESP_NETIF_DEFAULT_ETH();
esp_netif_t *eth_netif = esp_netif_new(&esp_netif_config);
// Set static ip
// esp_netif_dhcpc_stop(eth_netif);
// esp_netif_ip_info_t esp_netif_ip_info;
// esp_netif_ip_info.ip.addr = ESP_IP4TOUINT32(11,2,168,192);
// esp_netif_ip_info.netmask.addr = ESP_IP4TOUINT32(0,255,255,255);
// esp_netif_ip_info.gw.addr = ESP_IP4TOUINT32(1,2,168,192);
// esp_err_t ret2 = esp_netif_set_ip_info(eth_netif, &esp_netif_ip_info);
// ESP_ERROR_CHECK(ret2);
Lien entre les deux premières couches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On peut configurer les deux parties précédentes dans l'ordre de notre choix, mais c'est seulement une fois que
ces deux étapes sont réalisées qu'on peut attacher la couche TCP/IP à la couche physique/MAC.
Assez simple à faire, il suffit d'utiliser le code suivant :
.. code-block:: cpp
:linenos:
// Bind TCP/IP to Phy+MAC
esp_eth_netif_glue_handle = esp_eth_new_netif_glue(esp_eth_handle);
esp_netif_attach(eth_netif, esp_eth_netif_glue_handle);
On peut ensuite démarrer ethernet avec la fonction suivante :
.. code-block:: cpp
:linenos:
// Start ethernet
esp_eth_start(esp_eth_handle);
La partie applicative
~~~~~~~~~~~~~~~~~~~~~
Ici, on aura l'implémentation de notre serveur web. Ça se fait à partir de la librairie ``esp_http_server``
Rien de bien complexe ici quand on connait bien le fonctionnement de ce protocole.
Le code est le suivant :
.. code-block:: cpp
:linenos:
esp_err_t get_handler(httpd_req_t *req)
{
/* Send a simple response */
const char resp[] = "URI GET Response\n";
httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
ESP_LOGI(TAG, "good");
return ESP_OK;
}
httpd_uri_t uri_get = {
.uri = "/uri",
.method = HTTP_GET,
.handler = get_handler,
.user_ctx = NULL
};
Une fois ces trois étapes franchies, on peut démarrer QEMU avec la commande suivante :
.. code-block:: bash
:linenos:
/opt/qemu/build/qemu-system-xtensa -m 128 -nographic -machine esp32 \
-drive file=flash_img.bin,if=mtd,format=raw \
-net nic,model=open_eth \
-net user,host=192.168.2.1,net=192.168.2.0/24,hostfwd=tcp::80-:80 \
-net tap,script=no,downscript=no
On teste avec un simple ``curl http://127.0.0.1/uri`` et on voit que ça marche.
.. image:: ../images/esp32/QEMU_http_response.png
:width: 600
Ce qui ne marche pas
--------------------
L'IPv6
~~~~~~
Ne marche pas ni en wifi avec SLAAC, en wifi avec une ip statique,
ni avec QEMU. C'est ce qui m'a le plus fait perdre de temps.
En m'acharnant, je suis tombé sur ça 😤 🤬:
.. code-block:: bash
:linenos:
esp_err_t esp_netif_add_ip6_address(esp_netif_t *esp_netif, const esp_ip6_addr_t *addr, uint8_t preference)
{
return ESP_ERR_NOT_SUPPORTED;
}
Il manque clairement du travail du côté d'espressif pour implémenter la couche IPv6. C'est embêtant, ça nous
oblige à faire pleins de routes dans notre box, alors qu'on pourrait tout simplement pinger notre domotique de
l'extérieur avec du v6
.. note:: Il n'y a que la librairie loobback.c qui manque d'implémentation, dans
components/lwip/lwip/src/core/netif.c on trouve
``netif_add_ip6_address(struct netif *netif, const ip6_addr_t *ip6addr, s8_t *chosen_idx)``
qui est bel et bien implémentée. J'ai perdu du temps dessus, ça sera un NAT v4 pour l'instant.
Si à l'avenir j'arrive à faire marcher l'IPv6, je le documenterai.
L'interface tun0 et le bridging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
auand je lance ma commande QEMU, j'ai deux moyens d'accéder à mon ``http_server`` :
Soit via le ``hostfwd=tcp::80-:80``, soit via ``-net tap,script=no,downscript=no``.
Je fait un ``ip link set tap0 up et brctl addif br0 tap0`` pour que mon tap0 soit
pingable depuis le bridge en 192.168.2.15.
Et bien, un ``curl http://127.0.0.1/uri`` marche très bien, un ``curl http://192.168.2.15/uri``
ne parche pas, on à une erreur ``W (476492) opencores.emac: emac_opencores_isr_handler: RX frame dropped (0x14)``
J'ai essayé de mettre au max les buffers RX, testé toutes les configurations possible et imaginables,
impossible de passer par le bridge sans avoir un frame_drop. Grace au mod débug, j'arrive ici :
``components/esp_eth_src/esp_eth_mac_openeth.c``
.. image:: ../images/esp32/openeth_busy.png
:width: 600

313
esp32/vscodium_integration.rst Normal file
View File

@@ -0,0 +1,313 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Création d'un environnement vscodium
====================================
Le but ici va être d'automatiser un maximum d'actions, comme par exemple la compilation, le débug,
tout en les intégrant dans vscodium. Nous allons aussi configurer l'autocomplétion, la navigation
dans les fonctions et les librairies, et tout ce qui peut rendre notre IDE plus ergonomique.
Je vais essayer de maintenir cette section à jour au fur et à mesure que j'améliore
le projet.
.. warning:: pensez à importer les variables d'environnement avec esp_idf_import
comme vu dans l'installation si nécessaire.
Créer un nouveau project
------------------------
On commence par créer un projet a l'aide le l'utilitaire IDF :
.. code-block:: bash
idf.py create-project new_project
On peut ensuite ouvrir vscodium et ouvrir ce dossier ``Ctrl+O`` ou ``File -> Open Folder``.
Déclarer le $PATH et les variables d'environnement pour le terminal
-------------------------------------------------------------------
Si on lance notre terminal vscode et qu'on fait un ``export``, on ne retrouve pas les variables
d'environnement nécessaires à bon fonctionnement des outils IDF. Pour cela, il faut les renseigner
dans notre espace de travail.
Pour cela, on fait ``F1`` et on cherche settings.json.
.. image:: ../images/esp32/settings.json.png
:width: 600
Il va nous ouvrir le fichier ``.vscode/settings.json`` qui va contenir nos paramètres
propre au projet. Dans celui ci, on va renseigner toutes les variables d'environnement
qu'on à après un ``esp_idf_import`` comme vu dans la partie
`installation </esp32/installation.html#installation-et-configuration-de-l-esp-idf>`_.
On ajoute les lignes suivantes :
.. code-block:: json
:linenos:
{
"C_Cpp.intelliSenseEngine": "Tag Parser",
"terminal.integrated.cwd": "/root/test/new_project",
// environnement variables needeed by ESP_IDF
"terminal.integrated.env.linux": {
"ESP_IDF_VERSION": "5.1",
"ESP_ROM_ELF_DIR": "/opt/esp/esp-idf/.espressif/tools/esp-rom-elfs/20220823/",
"IDF_DEACTIVATE_FILE_PATH": "/tmp/tmpxj9n6nndidf_46523",
"IDF_PATH": "/opt/esp/esp-idf",
"IDF_PYTHON_ENV_PATH": "/opt/esp/esp-idf/.espressif/python_env/idf5.1_py3.10_env",
"IDF_TOOLS_EXPORT_CMD": "/opt/esp/esp-idf/export.sh",
"IDF_TOOLS_INSTALL_CMD": "/opt/esp/esp-idf/install.sh",
"IDF_TOOLS_PATH": "/opt/esp/esp-idf/.espressif",
"OPENOCD_SCRIPTS": "/opt/esp/esp-idf/.espressif/tools/openocd-esp32/v0.11.0-esp32-20221026/openocd-esp32/share/openocd/scripts",
"PATH": "/opt/esp/esp-idf/components/esptool_py/esptool:/opt/esp/esp-idf/components/espcoredump:/opt/esp/esp-idf/components/partition_table:/opt/esp/esp-idf/components/app_update:/opt/esp/esp-idf/.espressif/tools/xtensa-esp-elf-gdb/12.1_20221002/xtensa-esp-elf-gdb/bin:/opt/esp/esp-idf/.espressif/tools/xtensa-esp32-elf/esp-2022r1-11.2.0/xtensa-esp32-elf/bin:/opt/esp/esp-idf/.espressif/tools/esp32ulp-elf/2.35_20220830/esp32ulp-elf/bin:/opt/esp/esp-idf/.espressif/tools/openocd-esp32/v0.11.0-esp32-20221026/openocd-esp32/bin:/opt/esp/esp-idf/.espressif/python_env/idf5.1_py3.10_env/bin:/opt/esp/esp-idf/tools:/usr/local/sbin:/usr/local/bin:/usr/bin"
},
}
Configuration de l'extension C/C++
----------------------------------
Commencons par un simple code pour vérifier que tout fonctionne :
.. code-block:: c
:linenos:
#include <stdio.h>
#include <esp_log.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
void app_main(void)
{
int count=0;
while (true)
{
ESP_LOGI("NEW PROJECT", "my first test %d", count++);
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
On teste notre code avec les commandes suivantes :
.. code-block:: bash
:linenos:
idf.py set-target esp32
idf.py build
idf.py flash
idf.py monitor
Pour quitter le moniteur, il suffit d'un ``Ctrl+]``.
Ok, une fois que tout marche, on peut quitter le terminal.
On voit que vscodium affiche des erreurs au niveau des include qu'il ne trouve pas. Réglons tout ça.
En appuyant sur ``F1`` et en cherchant ``C/C++ configuration`` on trouve soit l'interface utilisateur soit un
racourci pour créer et renseigner le fichier ``.vscode/c_cpp_properties.json``.
Pour que la recherche intelligente foncrionne, il faut configurer l'extension pour qu'elle
sache ou chercher les librairies fournies par l'IDE. Des templates sont déjà disponibles
sur `le github d'espressif <https://github.com/espressif/vscode-esp-idf-extension/tree/master/templates/.vscode>`_.
.. image:: ../images/esp32/c_cpp_config.png
:width: 600
En m'inspirant de ce qu'esperssif fournit pour son extension vscodium,
voilà à quoi je suis arrivé pour que tout fonctionne bien :
.. code-block:: json
:linenos:
{
"configurations": [
{
"name": "ESP_IDF",
"includePath": [
"${workspaceFolder}/**",
"/opt/esp/esp-idf/components/**",
"/opt/esp/esp-idf/.espressif/tools/**"
],
"defines": [],
"compilerPath": "",
"cStandard": "c11",
"cppStandard": "c++17",
"intelliSenseMode": "linux-gcc-x64",
"browse": {
"path": [
"${workspaceFolder}/**",
"/opt/esp/esp-idf/components/**",
"/opt/esp/esp-idf/.espressif/tools/**"
],
"limitSymbolsToIncludedHeaders": false
}
}
],
"version": 4
}
Voilà, ça c'est pour que vscode et intellisense trouvent toutes les ressources dont ils ont besoin.
Configurer des tâches
---------------------
C'est ici, à mon sens, la fonctionnalié qui donne le plus de confort et qui va nous faire gagner un temps précieux.
Dans vscodium, on peut définir des tâches personnalisées pour le projet en cours, et les executer rapidement avec un raccourci clavier.
Dans un premier temps, je créer un script dans ``.scripts/tasks.sh`` que je rend executable, et dans lequel je vais coder toutes les actions
que je vais répéter souvent, comme builder le code, flasher l'esp, lancer QEMU pour débuger, etc. Voici le code, il est améliorable bien
entendu et on va y rajouter toutes les fonctionnalités que nous voudrons par la suite.
.. code-block:: bash
:linenos:
#!/bin/bash
function kill_idf {
for i in $(ps -elf | grep 'idf.py' | awk '{print $4}')
do
echo "found process $i"
kill $i
done
}
function build {
$IDF_PATH/tools/idf.py build
}
function flash {
kill_idf
$IDF_PATH/tools/idf.py flash
exit 0
}
function monitor {
kill_idf
$IDF_PATH/tools/idf.py monitor
exit 0
}
#######################
# Main
#######################
case $1 in
kill_idf)
echo "Killing all idf process"
kill_idf
;;
build)
echo "Building project"
build
;;
flash)
echo "Flashing memory"
flash
;;
monitor)
echo "Monitoring output"
monitor
;;
*)
echo "Missing args"
exit 1
;;
esac
Voilà, une fois ce script fait, on va y assigner des tâches vscodium. Je vais aller vite sur les explications, je
vous met un lien vers `la documentation officielle du fichier tasks.json <https://code.visualstudio.com/docs/editor/tasks>`_.
On créer un fichier ``.vscode/tasks.json`` et on y renseigne le code suivant :
.. code-block:: json
:linenos:
{
"version": "2.0.0",
"tasks": [
{
"label": "kill idf.py process",
"type": "shell",
"command": "${workspaceFolder}/.scripts/tasks.sh",
"args": [
"kill_idf"
],
"presentation": {
"reveal": "always",
"panel": "shared",
"close": false
},
"problemMatcher": []
},
{
"label": "build project",
"type": "shell",
"command": "${workspaceFolder}/.scripts/tasks.sh",
"args": [
"build"
],
"presentation": {
"reveal": "always",
"panel": "shared",
"close": false
},
"problemMatcher": []
},
{
"label": "flash esp memory",
"type": "shell",
"command": "${workspaceFolder}/.scripts/tasks.sh",
"args": [
"flash"
],
"presentation": {
"reveal": "always",
"panel": "shared",
"close": false
},
"problemMatcher": []
},
{
"label": "monitor",
"type": "shell",
"command": "${workspaceFolder}/.scripts/tasks.sh",
"args": [
"monitor"
],
"presentation": {
"reveal": "always",
"panel": "new",
"close": true
},
"problemMatcher": []
},
{
"label": "build, flash, and monitor",
"dependsOrder": "sequence",
"dependsOn": ["build project", "flash esp memory", "monitor"],
"problemMatcher": []
},
]
}
Et voilà, comme vous pouvez le voir, vous avez toutes les tâches de compilation, execution, et debug imtégrées à
vscodium. on peut y accéder en tappant ``F1 -> run task``, et pour gagner du temps, on peut même définir un raccourci clavier
Pour gagner encore une étape.
.. image:: ../images/esp32/run_tasks.png
:width: 600
Et voilà, un appui sur ``Ctrl+F1`` me donne accès à autant de tâches que je voidrai en créer.
.. image:: ../images/esp32/tasks.png
:width: 600

BIN
images/atom_dark_theme_extension.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 174 KiB

BIN
images/emoji_extension.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 147 KiB

BIN
images/esp32/QEMU_gdb_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 174 KiB

BIN
images/esp32/QEMU_http_response.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 249 KiB

BIN
images/esp32/c_cpp_config.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 123 KiB

BIN
images/esp32/debug.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 159 KiB

BIN
images/esp32/include_error.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

BIN
images/esp32/include_error_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
images/esp32/ms_cpp_extension.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
images/esp32/native_debug_extension.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 92 KiB

BIN
images/esp32/openeth_busy.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
images/esp32/run_tasks.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
images/esp32/settings.json.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

BIN
images/esp32/tasks.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 66 KiB

BIN
images/example_image.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
images/reStructuredText_extension.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 76 KiB

126
index.rst Normal file
View File

@@ -0,0 +1,126 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. toctree::
:maxdepth: 2
:hidden:
:glob:
sphinx/index.rst
.. toctree::
:maxdepth: 2
:hidden:
:caption: Configuration côté utilisateur
:glob:
xorg/*
.. toctree::
:maxdepth: 2
:hidden:
:caption: Configuration côté serveur
:glob:
server/*
.. toctree::
:maxdepth: 2
:hidden:
:caption: Programmation
:glob:
esp32/index.rst
.. toctree::
:maxdepth: 2
:hidden:
:caption: Sheat Sheet
:glob:
sheatsheet/*
.. toctree::
:maxdepth: 2
:hidden:
:caption: Licence
README.md
LICENSE.md
Bienvenue sur la documentation d'UnixYourBrain !
================================================
Je vais avec ce site créer une doc pour toutes mes manip et bidouilles informatiques.
Le passage à l'ipv6 :
---------------------
Bien que de nombreux sites soient accessibles en ipv6, ce n'est pas le cas de tous.
Un ``host qwant.com`` ou ``host startpage.com`` nous montrent que des sites suffisament populaires ou fréquentés ne sont toujours pas passés à l'ipv6.
De plus, certains opérateurs, comme free pour sa 4g, ne le prennent pas complètement en charge, voir pas du tout.
Cela mène généralement à des configurations mixtes ipv4/ipv6 souvent mal maitrisées, complexes et brouillon.
Je vais donc m'imposer quelques règles de conduite pour configurer proprement, tout comprendre comme il faut, et l'expliquer dans cette documentation.
Ipv6 first
~~~~~~~~~~
Que ça soit pour la configuration IP, ou des services, je vais d'abbord configurer l'ipv6, en ipv6 only autant que possible.
Côté client :
* Je configurerai d'abord l'ipv6, et une fois que je me serai assuré qu'elle marche bien, j'ajouterai l'ipv4 pour les sites / serveurs qui ne la gèrent pas encore.
* Je configurerai mes bridges et mes machines virtuelles en ipv6 only.
Côté serveur :
* Pour la configuration IP, je procèderai de la même manière que pour le côté client.
* pour les services personnels et d'administration, je les configuerai uniquement en ipv6
* Pour les services publics, je les configurerai en ipv6 first
Machine virtuelles et test :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pour tester mes différentes configurations, je vais utiliser une machine virtuelle.
Tout ce qui sera vu dans cette documentation sera testé sur une machine virtuelle locale.
Vous pourrez le reporoduire chez vous sans poséder d'IP publique, de serveur ou quoi que ce soit d'autre.
Rappels :
---------
Avant de commencer, je vais faire un rappel des points suivants :
Ipv6
~~~~
Je vais bien entendu faire un rappel de l'ipv6, de ce que j'en ai compris.
J'étofferai au fur et à mesure de mes découvertes et de mes trouvailles.
Étant abonné freebox, je vais aussi expliquer comment free gère et met en place l'ipv6.
La documentation avec Sphinx
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Cette documentation est faite à l'aide du framework `Sphinx <https://www.sphinx-doc.org/fr/master/>`_.
C'est un outil qui permet d'écrire de la documentation simplement au format
`reStructuredText (.rst) <https://docutils.sourceforge.io/rst.html>`_.
Il dispose aussi d'un plugin pour la syntaxe `Markdown (.md) <https://daringfireball.net/projects/markdown/>`_
Je ferai donc une brève documentation de ces syntaxes,
et je créerai peut être une documentation sur comment installer et utiliser Sphinx.
Configuration IP
~~~~~~~~~~~~~~~~
Sur un Linux récent, nous avons deux moyens de gérer la configuration IP : networking et systemd-networkd.
Pour la configuration, côté client comme serveur, je vais abandonner le service networking pour utiliser uniquement systemd-networkd.
Iptables
~~~~~~~~
Tout au long des manipulations, je vais créer les règles iptables pour sécuriser les outils que je mettrai en place.
Tout ce qu'il y a à connaitre sera reporté dans une documentation consacrée à iptables

4
live-reload.sh Executable file
View File

@@ -0,0 +1,4 @@
#!/bin/bash
rm -fr /tmp/sphinx-livereload/
sphinx-reload --build-dir /tmp/sphinx-livereload/ ./

161
server/gitlist.rst Normal file
View File

@@ -0,0 +1,161 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Installation de GitList
=======================
GitList est une interface web simple et légère écrite en PHP qui permet
de visionner l'ensemble de nos dépots git sur un serveur.
.. warning:: la version 2.0.0 contient un bug qui empèche de
parcourir les différents dépots, nous installeront donc la
version 1.1.1
.. note:: J'ai installé GitList sous Debian 11, pour d'autres distributions il
faudra adapter quelques paramètres, comme par exemple sous ArchLinux :
- l'utilisateur apache est ``http`` et non ``www-data``,
- le home directory de l'utilisateur apache est ``/srv/http`` et non ``/var/www``.
configuration d'apache
----------------------
On va configurer un simple vhost, en suivant les `recommendations
fournies par le développeur <https://github.com/klaussilveira/gitlist/wiki/Configuring-Gitlist-in-CENTOS7>`_.
On créer le vhost ``/etc/apache2/sites-available/gitlist.conf`` :
.. code-block:: apache
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerAdmin webmaster@yourdomain.domain
ServerName gitlist.yourdomain.domain
DocumentRoot /var/www/gitlist
<Directory /var/www/gitlist/>
Options FollowSymLinks
AllowOverride All
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/gitlist-error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
# enable HTTP/2, if available
Protocols h2 http/1.1
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/gitlist.yourdomain.domain/cert.pem
SSLCertificateKeyFile /etc/letsencrypt/live/gitlist.yourdomain.domain/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/gitlist.yourdomain.domain/chain.pem
</VirtualHost>
</IfModule>
Installation de gitlist
-----------------------
On se place dans notre repertoire root, on télécharge le zip, on l'extrait :
.. code-block:: bash
cd /var/www/gitlist
wget https://github.com/klaussilveira/gitlist/releases/download/1.1.1/gitlist-1.1.1.zip
unzip gitlist-1.1.1.zip
Configuration
-------------
Quand on ouvre notre navigateur, on fait face a plusieurs messages d'erreur.
Configurons notre serveur pour que tout fonctionne correctement :
on créer un dossier ``cache`` et on attribue les droits du répertoire racine à l'utilisateur
apache (``www-data``).
.. code-block:: bash
mkdir cache
chown -R www-data:www-data ./
On créer ensuite le fichier ``config.ini`` à partir du fichier ``config.ini-example`` fourni :
.. code-block:: bash
cp config.ini-example config.ini
vi config.ini
On modifie la ligne suivante pour indiquer le chemin des dépots :
.. code-block:: php
repositories[] = '/home/git/repositories/'
Et voilà, on à la liste de nos dépots. Il reste une erreur quand on essaye de
parcourir un dépot. cela est du au fait que l'utilisateur ``www-data`` qui utilise la
commande git n'as pas les droits sur le dossier du dépot. Git renvoie l'erreur suivante :
``fatal: detected dubious ownership in repository at '/home/git/repositories/doc.git' To add an exception for this directory, call: git config --global --add safe.directory /home/git/repositories/doc.git``.
La solution est dans le message, on execute la commande suivante pour chaque dépot :
.. code-block:: bash
sudo -u www-data git config --global --add safe.directory /home/git/repositories/doc.git
.. warning:: git créer un fichier .gitconfig dans le home directory pour stocker ces paramètres.
il faut s'assurer que l'utilisateur apache à bien accès en écriture à son home directory.
Sous debian, ``www-data`` utilise ``/var/www`` comme home directory. on le rend accessible en
écriture :
.. code-block:: bash
chown www-data:www-data /var/www
Rendre les dépots clonable par https (en téléchargement uniquement)
-------------------------------------------------------------------
Pour que git puisse cloner un dépot, il besoin de traitements spéciaux côté serveur.
Heureusement, git est foutni avec un binaire ``git-http-backend``, qui fait ce traitement.
Il suffit de le passer comme script cgi à apache.
On commence à activer les mods nécessaires pour apache :
.. code-block:: bash
a2enmod cgi alias env
On ajoute ensuite la configuration suivante à notre vhost :
.. code-block:: apache
SetEnv GIT_PROJECT_ROOT /data/git
SetEnv GIT_HTTP_EXPORT_ALL
ScriptAlias /git /usr/lib/git-core/git-http-backend
<Directory "/usr/lib/git-core/">
Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
Require all granted
</Directory>
Alias /git /data/git
Pour terminer, on ajouste le config.ini de notre site, notament le http_url_subdir.
.. code-block:: php
; http remote
show_http_remote = true ; display remote URL for HTTP
http_host = '' ; host to use for cloning via HTTP (default: none => uses gitlist web host)
use_https = true ; generate URL with https://
http_url_subdir = 'git/' ; if cloning via HTTP is triggered using virtual dir (e.g. https://example.com/git/repo.git)
; has to end with trailing slash
http_user = '' ; user to use for cloning via HTTP (default: none)
http_user_dynamic = false ; when enabled, http_user is set to $_SERVER['PHP_AUTH_USER']

330
server/rutorrent.rst Normal file
View File

@@ -0,0 +1,330 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Installation de ruTorrent
=========================
Prérequis
---------
Pour l'installation de ruTorrent, il faut au minimum avoid les paquets suivants s'installés :
- apache 2.4.x
- rtorrent 0.9.7
- libtorrent 0.13.7
- ruTorrent 3.10
Installation de rtorrent
------------------------
Créer un home directory :
.. code-block:: bash
mkdir /data/rtorrent
cd /data/rtorrent
Configurer rtorrent avec le script du développeur : `<https://github.com/rakshasa/rtorrent/wiki/CONFIG-Template>`_
.. code-block:: bash
curl -Ls "https://raw.githubusercontent.com/wiki/rakshasa/rtorrent/CONFIG-Template.md" \
| sed -ne "/^######/,/^### END/p" \
| sed -re "s:/home/USERNAME:$HOME:" > ./.rtorrent.rc
Éditer la config :
.. code-block:: bash
## On modifie les chemins
method.insert = cfg.basedir, private|const|string, (cat,"/data/rtorrent/")
method.insert = cfg.watch, private|const|string, (cat,(cfg.basedir),"torrent/")
...
## Commenter les lignes suivantes
#execute.throw = sh, -c, (cat,\
# "mkdir -p \"",(cfg.download),"\" ",\
# "\"",(cfg.logs),"\" ",\
# "\"",(cfg.session),"\" ",\
# "\"",(cfg.watch),"/load\" ",\
# "\"",(cfg.watch),"/start\" ")
...
## Maxer l'utilisation de la ram
pieces.memory.max.set = 1000M
...
## Loguer les connexions RPC
log.xmlrpc = (cat, (cfg.logs), "xmlrpc.log")
...
## Umask pour du 755/644
system.umask.set = 0022
...
## On démarre le téléchargement pour tout les torrents déposés dans le dossier
## Add torrent
#schedule2 = watch_load, 11, 10, ((load.verbose, (cat, (cfg.watch), "*.torrent")))
## Add & download straight away
schedule2 = watch_start, 10, 10, ((load.start_verbose, (cat, (cfg.watch), "*.torrent")))
...
## On lance le socket unix pour la communication avec ruTorrent, en 777 pour qu apache puisse s'y connecter
#system.daemon.set = true
network.scgi.open_local = (cat,(session.path),rpc.socket)
execute.nothrow = chmod,777,(cat,(session.path),rpc.socket)
Créer les répertoires :
.. code-block:: bash
mkdir {download,log,.session,torrent}
Ajouter un utilisateur rtorrent :
.. code-block:: bash
adduser --disabled-login --disabled-password --home /data/rtorrent/ --system rtorrent
Affecter les bons droits :
.. code-block:: bash
chown -R rtorrent:www-data /data/rtorrent/
Lancer rtorrent pour tester la config :
.. code-block:: bash
sudo -u rtorrent rtorrent
Configuration d'apache
----------------------
On créer le vhost ``/etc/apache2/sites-available/rutorrent.conf`` :
.. code-block:: Apacheconf
<VirtualHost 192.168.1.100:8083>
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html
<Directory /var/www/html/>
Options Indexes Includes FollowSymLinks MultiViews
AllowOverride all
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
On ouvre le port dans ``/etc/apache2/ports.conf`` :
.. code-block:: Apacheconf
Listen 8083
On charge la configuration et on redémarre apache :
.. code-block:: bash
a2ensite rutorrent.conf
systemctl restart apache2
Installation de ruTorrent
-------------------------
On trouve la dernière version stable `ici <https://github.com/Novik/ruTorrent/releases>`_ :
.. code-block:: bash
cd /var/wwww
wget https://github.com/Novik/ruTorrent/archive/v3.10.zip
unzip v3.10.zip
mv ruTorrent-3.10/ html
rm v3.10.zip
chown -R www-data:www-data html
On modifie la configuration de rutorrent : ``conf/config.php`` :
.. code-block:: bash
// On commente le chemin socket ip, et on file le soket unix
//$scgi_port = 5000;
//$scgi_host = "127.0.0.1";
// For web->rtorrent link through unix domain socket
// (scgi_local in rtorrent conf file), change variables
// above to something like this:
//
$scgi_port = 0;
$scgi_host = "unix:///data/rtorrnet/.session/rpc.socket";
Améliorations
-------------
Si on veut mettre des limites de connection, on rajoute au ``.rtorrent.rc`` :
.. code-block:: bash
# Global upload and download rate in KiB.
# "0" for unlimited
throttle.global_down.max_rate.set_kb = 1000
throttle.global_up.max_rate.set_kb = 1000
Si on veut que rtorrent arrête le téléchargement en cas d'espace disque faible :
.. code-block:: bash
# Close torrents when disk-space is low.
schedule2 = low_diskspace,5,60,close_low_diskspace=5000M
Si on veut que le plugin mediainfo fonctionne :
.. code-block:: bash
apt install mediainfo
Si on veut que le plugin spectrogram fonctionne :
.. code-block:: bash
aptitude install sox
Si on veut que le pluggin unpack marche :
.. code-block:: bash
apt install unrar
Pour optimiser les downloads avec peu de seed :
.. code-block:: bash
## Tracker-less torrent and UDP tracker support
## (conservative settings for 'private' trackers, change for 'public')
dht.mode.set = on
# port for DTH (default 6881)
#dht.port.set = 6881
# Use peer exchange
protocol.pex.set = yes
# DTH use udp by default
trackers.use_udp.set = yes
Pour avoir le pays des peers, il faut installer GeoIP :
.. code-block:: bash
apt install php-geoip geoip-database
systemctl restart apache2.service
systemctl restart php7.3-fpm.service
Iptables
--------
On Ajoute les règles suivantes dans notre firewall :
.. code-block:: bash
ip6tables -A INPUT -i enp1s0 -p tcp --dport 50000 -j ACCEPT
ip6tables -A INPUT -i enp1s0 -p udp --dport 6881 -j ACCEPT
iptables -A INPUT -i enp1s0 -p tcp --dport 50000 -j ACCEPT
iptables -A INPUT -i enp1s0 -p udp --dport 6881 -j ACCEPT
Script de gestion
-----------------
Si on ne veut pas que rtorrent se lance automatiquement au démarrage via systemd,
on peut faire un script tout simple qui démarre rtorrent en mode daemon
et configure les règles iptables.
.. important:: Pour cela, il faut d'abord aller dans ``/data/rtorrent/.rtorrent.rc`` et modifier le paramètre : ``system.daemon.set = true``
Voici le script qui permet de démarrer ou arrêter rtorrent.
.. warning:: Attention, rtorrent met du temps à s'arrêter, il à beaucoup de connections à fermer.
.. code-block:: bash
#!/bin/bash
function start {
ps -elf | grep /usr/bin/rtorrent | grep -v "sudo\|grep"
if (( $? == 0 )); then
printf "rtorrent alerady started\n"
exit 1
fi
printf "starting rtorrent...\n"
sudo -u rtorrent nohup /usr/bin/rtorrent &
ip6tables -A INPUT -i enp1s0 -p tcp --dport 50000 -j ACCEPT
ip6tables -A INPUT -i enp1s0 -p udp --dport 6881 -j ACCEPT
iptables -A INPUT -i enp1s0 -p tcp --dport 50000 -j ACCEPT
iptables -A INPUT -i enp1s0 -p udp --dport 6881 -j ACCEPT
}
function stop {
ps -elf | grep /usr/bin/rtorrent | grep -v "sudo\|grep"
if (( $? == 1 )); then
printf "rtorrent alerady stoped\n"
exit 1
fi
printf "stoping rtorrent...\n"
kill $(cat /data/rtorrent/.session/rtorrent.pid)
ip6tables -D INPUT -i enp1s0 -p tcp --dport 50000 -j ACCEPT
ip6tables -D INPUT -i enp1s0 -p udp --dport 6881 -j ACCEPT
iptables -D INPUT -i enp1s0 -p tcp --dport 50000 -j ACCEPT
iptables -D INPUT -i enp1s0 -p udp --dport 6881 -j ACCEPT
}
function usage {
cat <<EOF
rtorrent.sh
start or stop rtorrent
-h --help : Print this help
-s --start : Start rtorrent
--stop : Stop rtorrent
EOF
exit 0
}
##################
# MAIN
##################
if [[ -z $1 ]]; then
usage
exit 1
fi
options=$(getopt -o sh -l start,stop,help -- "$@")
if [ $? != 0 ]
then
usage
exit 1
fi
eval set -- "$options"
while true; do
case "$1" in
-s|--start)
start
break
;;
--stop)
stop
break
;;
-h|--help)
usage
;;
*)
usage
shift
break
;;
esac
shift
done
exit 0;

122
sheatsheet/git.rst Normal file
View File

@@ -0,0 +1,122 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Git Sheatsheet
==============
Initialisation d'un dépot
-------------------------
``git init (-b master branch name) (--bare pour un dépot distant sans work area)``
Clonage, synchronisation et update
----------------------------------
Clonage
``git clone <url>``
Pousser un dépot local sur un dépot distant qui vient d'être initalisé
``git remote add origin ssh://user@git-server/path/to/myrepo.git``
``git push --set-upstream origin master``
Synchronisation
``git fetch``
``git pull <remote(origin)> <branch(master)>``
Update
``git push <remote(origin)> <branch(master)>``
Versionning
-----------
Pour versionner, il faut utiliser git tag.
``git tag (-a vx.x.x-rcx) (-m "comment")``
Pour synchroniser le tag avec le dépot distant,
il faut un push spécifique pour la version :
``git push branch(origin) tag(vx.x.x-rcx)``
pour supprimer un tag
``git tag -d vx.x.x``
Et pour le supprimer sur le dépot distant
``git push --delete origin v1.1.0``
Commit
------
``git commit (-a all modified files) (-m message)``
Navigation
----------
``git ls-tree``
Merge des commit
----------------
Git créer un snapshot à chaque commit, cela améliore les
performances par rapport à d'autres systèmes de versionning,
mais cela prend vite aussi beaucoup de place.
Pour alléger cela, on peut merger une suite de commit en
un seul avant de push sur le serveur. On utilise la commande suivante :
``git rebase -i(--interactive) <merge-after-this-commit>``
et on remplace les derniers "pick" dans le shell interactif par squash.
.. code-block:: bash
:linenos:
pick 309769c updating .Xressources configuration
squash 39a45ab updating .Xressources configuration
squash 76f1543 updating .Xressources configuration
example :
``git rebase -i HEAD~5``
``git rebase -i 6919b24b1285f00b59eae416faf7ccfba0987843``
``git rebase -i origin/master`` (pour push un seul commit depuis la dernièrebase
synchronisation avec la branche master de notre dépot distant)
Configuration générale
----------------------
``git config --global init.defaultBranch master``
``git config --global user.email "you@example.com"``
``git config --global user.name "Your Name"``
Workflow
--------
``git pull``
aussi souvent que nmécessaire
- ``git add``
- ``git commit``
``git rebase -i origin/master``
``git push``

21
sphinx/documentation.rst Normal file
View File

@@ -0,0 +1,21 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Création et organisation de la documentation
============================================
L'arborescence de notre documentation se fera directement dans les fichiers index.rst via
l'attribut ``.. toctree::``
Les différents attributs pour ce bloc sont documentés ici : `Directives toctree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
Je vous conseille de faire un tour sur ce lien qui vous montre toutes les spécificités de ce que peut inclure sphinx dans votre documentation grace
à la syntaxe rst.
J'utilise notament la directive :hidden dans mon indec pour ne pas que le bloc toctree s'affiche sur la page mais soit bien pris en compte par le menu

18
sphinx/index.rst Normal file
View File

@@ -0,0 +1,18 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
La documentation avec Sphinx
============================
.. toctree::
:maxdepth: 2
installation.rst
documentation.rst
syntax.rst

270
sphinx/installation.rst Normal file
View File

@@ -0,0 +1,270 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Installation de Sphinx
======================
Introduction
------------
`Sphinx <https://www.sphinx-doc.org/fr/master/>`_ est un framework écrit en `Python <https://www.python.org/>`_
qui va parser notre documentation dans la syntaxe `ReSrtucturedText <https://docutils.sourceforge.io/rst.html>`_
et la compiler au format html. Le dossier pourra donc être ensuite utilisé par un serveur web comme apache ou nginx
pour accéder en ligne à cette documentation. Sphinx porpose aussi d'autres formats de sortie,
comme le PDF, l'ePub, le manpage, etc. Sphynx est aussi capable d'utiliser des librairies tiers pour
lire d'autres syntaxes comme le MarkDown.
.. important:: Le dossier de travail pour la suite de cette page sera ``/var/www/html``
Installation
------------
Toutes les librairies nécessaires sont disponible dans le gestionnaire de paquets debian.
Il suffit d'un ``apt install``.
.. code-block:: bash
apt install apache2 python3 python3-sphinx python3-sphinx-autobuild python3-sphinx-rtd-theme python3-pip build-essential
Création d'un nouveau projet
----------------------------
On commence par se placer dans notre dossier html, et on initialise le projet :
.. code-block:: bash
cd /var/www/html
sphinx-quickstart
Et on répond aux questions posées :
.. code-block::
:emphasize-lines: 11,14,15,16,24
Welcome to the Sphinx 4.2.0 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: Unixyourbrain Documentation
> Author name(s): beastie
> Project release []: 0.1
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: fr
Creating file /var/www/test/source/conf.py.
Creating file /var/www/test/source/index.rst.
Creating file /var/www/test/Makefile.
Creating file /var/www/test/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file /var/www/test/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
Sphinx nous a automatiquement créé un dossier source dans lequel sera organisé notre documentation.
Il créer aussi un Makefile pour générer le site. Dans le dossier source, on retrouve deux fichiers
qui vont nous intéresser, le fichier conf.py, qui contient la configuration propre à sphinx, et
un fichier index.rst qui sera le point d'entrée de notre documentation.
Configuration du thème ReadTheDocs
----------------------------------
dans le fichier ``source/conf.py`` il faut modifier le paramètre ``html_theme``
.. code-block:: python
html_theme = 'sphinx_rtd_theme'
on peut aussi ajouter quelques options pour plus de confort
.. code-block:: python
html_theme_options = {
'collapse_navigation': False,
'prev_next_buttons_location': 'both',
}
Les options du thème sont documentées
`ici <https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html>`_
Modification du CSS
-------------------
Le thème readthedocs ne propose pas les blocs de code sur fond sombre. Heureusement,
sphinx nous permet de rajouter du css et du javascript personnalisé. Pour ça, on créer le fichier
``source/_static/css/custom.css``. On y ajoute les lignes suivantes :
.. code-block:: css
.rst-content pre.literal-block, .rst-content div[class^="highlight"] {
background: #212121;
color: #fff;
border: 1px solid #3a3a3a;
}
.rst-content div.highlight span.linenos {
border-right: 1px solid #3a3a3a;
}
.rst-content div[class^="highlight"] pre .hll {
background-color: #13533b;
}
Une fois le CSS créé, il faut le renseigner dans la configuration de sphinx.
On édite le fichier ``soucre/conf.py`` et on ajoute après les lignes 3 à 5 après le
paramètre ``html_static_path``
.. code-block:: python
html_static_path = ['_static']
html_css_files = [
'css/custom.css',
]
Si vous modifiez le CSS après avoir lancé un liveserveur, celui ci ne sera pas automatiquement
pris en compte. Il faudra supprimer le dossier ``_build``.
(cf. `Utilisation d'un liveserveur <#utilisation-d-un-liveserveur>`__)
Utilisation d'un liveserveur
----------------------------
Pour faclilter l'édition de la documentation, sphinx nous fournit le paquet
``python3-sphinx-autobuild``. Dans le dossier ``/var/www/html``,
il suffit de lancer la commande suivante :
.. code-block:: bash
sphinx-autobuild source/ _build/
On peut désormais se connecter à l'adresse suivante : `<http://127.0.0.1:8000>`_. À chaque sauvegarde
d'un fichier de documentation, le liveserveur va régénérer les fichiers html, et recharger
la page automatiquement.
.. attention::
le liveserveur ne régénère pas automatiquement le menu. lors d'un changement dans le
menu il faut supprimer notre dossier _build
.. code-block:: bash
rm -fr _build
Compilation et mise en ligne
----------------------------
Pour mettre en ligne notre documentation, il faut d'abbord générer l'arborescence
html à l'aide de sphinx. On le fait à l'aide de la commande make fournie par
le paquet build-essential.
.. code-block:: bash
make html
Sphinx créer un dossier build pour générer la documentation.
on retrouve dans ce dossier un dossier html contenant le site de notre documentation.
C'est ce dossier que l'on va présenter comme racine du site web.
Pour le mettre en ligne, il suffit de configurer un vhost apache avec la configuration
suivante :
.. code-block:: apacheconf
<VirtualHost *:80>
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html/build/html
<Directory /var/www/html/build/html/>
Options -Indexes -FollowSymLinks
AllowOverride none
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
Création d'un venv
------------------
.. note::
Depuis peu on ne peut plus unstaller des paquets avec pip en global sur notre
distribution, il va donc falloir créer un environnement virtuel python.
.. code-block:: bash
:linenos:
python -m venv .venv
source .venv/bin/activate
pip install sphinx_rtd_theme
Prise en charge du format MarkDown
----------------------------------
Pour interpréter le MarkDown, Sphinx utilise la librairie python `MyST <https://myst-parser.readthedocs.io/en/latest/>`_
On l'installe à partir du gestionnaire de paquets python `pip <http://link>`_
.. code-block:: bash
pip install --upgrade myst-parser
On ajoute ensuite les lignes suivantes dans ``soucre/conf.py``
.. code-block:: python
extensions = [
'myst_parser'
]
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}
Ajout su support pour les emoji
-------------------------------
Pour ça il faut unstaller le package python ``sphinxemoji``
.. code-block:: bash
pip install --upgrade sphinxemoji
On configure ensuite sphinx afin qu'il utilise l'extension :
.. code-block:: python
extensions = [
'sphinxemoji.sphinxemoji',
]
.. warning::
Ce module n'est pas compatible avec ``sphinx-autobuild``, il faut
donc désactiver cette option dans la configuration pour pouvoir
utiliser le live serveur.
Voilà, c'est fini, vous trouverez toutes les emoji et toutes les explications `ici <https://sphinxemojicodes.readthedocs.io/en/stable/>`_ |:smile:|

214
sphinx/syntax.rst Normal file
View File

@@ -0,0 +1,214 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
La syntaxe reStructuredText
===========================
Les titres
----------
Les liens
---------
.. code-block:: rst
`ReSrtucturedText <https://docutils.sourceforge.io/rst.html>`_
Resultat :
`ReSrtucturedText <https://docutils.sourceforge.io/rst.html>`_
Les listes
----------
.. code-block:: rst
Bullet lists:
- This is item 1
- This is item 2
Resultat :
Bullet lists:
- This is item 1
- This is item 2
.. code-block:: rst
Enumerated lists:
3. This is the first item
4. This is the second item
#. Auto ennumerated item
Resultat :
Enumerated lists:
3. This is the first item
4. This is the second item
#. Auto ennumerated item
Plus d'infos `ici <https://docutils.sourceforge.io/docs/user/rst/quickref.html#bullet-lists>`_.
Les blocs
---------
.. code-block:: rst
.. error:: text
Resultat :
.. error:: text
.. code-block:: rst
.. warning:: text
Resultat :
.. warning:: text
.. code-block:: rst
.. note:: text
Resultat :
.. note:: text
.. code-block:: rst
.. tip:: text
Resultat :
.. tip:: text
.. code-block:: rst
.. important:: text
Resultat :
.. important:: text
Les Maths
---------
.. code-block:: rst
.. math::
(a + b)^2 = a^2 + 2ab + b^2 \\
= a^2 - 2ab + b^2
Resultat :
.. math::
(a + b)^2 = a^2 + 2ab + b^2 \\
= a^2 - 2ab + b^2
Plus d'infos sur ce bloc `ici <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#math>`_.
Le code
-------
analysé avec la librairie `Pygments <https://pygments.org/>`_. Pour en
savoir plus sur son utilisation et les langages supportés, c'est `ici <https://pygments.org/languages/>`_
Code "inline"
~~~~~~~~~~~~~
Le code "inline" est un génère un objet html <inline> qui s'intègre dans le texte comme ``ceci``
.. code-block:: rst
``code``
Resultat :
``code``
Code "block"
~~~~~~~~~~~~
Le code "block" génère un bojet html <block>. La syntaxe rst est la suivante :
.. code-block:: rst
.. code-block:: bash
:linenos:
:lineno-start: 5
:caption: caption
:name: a label
:emphasize-lines: 2,6
#!/bin/bash
function start() {
while :
do
discord --no-sandbox $1
done
}
.. code-block:: bash
:linenos:
:lineno-start: 5
:caption: a caption
:name: a label
:emphasize-lines: 2,6
#!/bin/bash
function start() {
while :
do
discord --no-sandbox $1
done
}
| Les paramètres ne sont pas très compliqués :
| ``:lineos:`` : affiche les numéros de ligne
| ``:linestart: number`` : affiche les numéros de ligne
| ``:caption: string`` : affiche un titre au bloc de code
| ``:name: string`` : ???
| ``:emphasize-lines: number list coma separated`` : met en surbrillance les lignes renseignées par cette option
Inclure un fichier de Code
~~~~~~~~~~~~~~~~~~~~~~~~~~
On peut avec Sphinx inclure un fichier de code dans in bloc.
Ici, j'inclus le code de cette page dans un bloc de code rst
.. code-block:: rst
.. literalinclude:: syntax.rst
:language: rst
Resultat :
.. literalinclude:: syntax.rst
:language: rst
Les images
----------
.. code-block:: rst
.. image:: ../images/example_image.png
:width: 400
:alt: Alternative text
Resultat :
.. image:: ../images/example_image.png
:width: 400
:alt: Alternative text

146
xorg/urxvt.rst Normal file
View File

@@ -0,0 +1,146 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Installation de rxvt unicode
============================
Rxvt-unicore ou urxvt est un terminal léger, configurable et facile d'accès. C'est
une bonne alternative a xterm, il est plus puissant tout en restant aussi simple,
et évite d'installer des terminaux trop lourds comme ceux fournis avec les plus
grosses interfaces graphiques.
Prérequis
---------
Aucun, sous arch, il suffit d'ouvrir un shell et de l'installer.
.. code-block:: bash
pacman -S rxvt-unicode
Configuration
-------------
La configuration se fait depuis .Xresources, soit depuis ``/etc/X11/xinit/`` pour la configuration globale,
ou depuis ``~/.Xresources`` pour la surdéfinition des paramètres par l'utilisateur.
voici les paramètres généraux que j'utilise, plus d'infos dans le manpage (ou via un moteur de recherche |:smile:|)
.. code-block:: bash
!-------------------------
! Global Term Parameters
!-------------------------
*.foreground:#abb2bf
*.foreground-dark:#5c6370
*.background:#282c34
*.background-light:#333842
*.background-dark:#21252b
*.cursorColor:#98c379
*.scrollBar:false
*.saveLines:65535
*.termName:rxvt-unicode
*.font:xft:DejaVu Sans Mono:style=Regular:size=12:antialias=true
*.boldFont:xft:DejaVu Sans Mono:style=Bold:size=12:antialias=true
!*.font:xft:Material Icons:style=Regular:size=14:antialias=true
!*.boldFont:xft:Iosevka Nerd Font Mono:style=Bold:size=14:antialias=true
!*.letterSpace:-4
*.intensityStyles:true
*.iconFile:/usr/share/icons/ePapirus/96x96/apps/urxvt.svg
*.cutchars:"()<>=[]{}|\"\`'*"
*.iso14755:false
*.utf8:true
*.geometry:87x27
!-------------------------
! One Dark theme colors
!-------------------------
!Black & grey
!*color0:#21252b
!*color8:#282c34
!Red & lightred
*color1:#e06c75
*color9:#e06c75
!Green & lightgreen
*color2:#98c379
*color10:#98c379
!Yellow & lightyellow
*color3:#ffd766
*color11:#ffd766
!Blue & lightblue
*color4:#61afef
*color12:#61afef
!Magenta & lightmagenta
*color5:#c678dd
*color13:#c678dd
!Cyan & lightcyan
*color6:#56b6c2
*color14:#56b6c2
!Lightgrey & white
!*color7:#333842
!*color15:#d7dae0
!-------------------------
! Rxvt Only
!-------------------------
URxvt.perl-ext:-confirm-paste
! Pseudo Transparency
!URxvt.transparent: true
!URxvt.shading: 50
!URxvt.blurRadius: 20
! True Transparency (works only with a composite manager like xcompmgr !)
!URxvt.depth: 32
!URxvt.background:[50]#282c34
!URxvt.background:rgba:2800/2c00/3400/F000
Utilisation des extensions perl
-------------------------------
Le point fort d'urxvt c'est de pouvoir charger des extensions en perl et le rendre hautement configurable.
sous arch, il y en a installées par defaut dans ``/usr/lib/urxvt/perl``. Si vous ne trouvez pas la votre,
il faudra la télécharger dans ce dossier.
Pour les configuer, toujours dans ``.Xresources`` il faut ajouter les lignes suivantes :
.. code-block:: bash
URxvt.perl-lib:/usr/lib/urxvt/perl
URxvt.perl-ext-common:tabbed,resize-font,matcher
!Configure font size extension :
URxvt.keysym.C-Up: resize-font:bigger
URxvt.keysym.C-Down: resize-font:smaller
URxvt.keysym.C-equal: resize-font:reset
URxvt.keysym.C-slash: resize-font:show
!Configure Url Launcher
URxvt.url-launcher: firefox
URxvt.matcher.button: C-1
URxvt.keysym.C-u: perl:matcher:select
!Configure tabbed extension according terminal.sexy
!*.color0: #101010
!*.color1: #008800
*.tabbed.tabbar-bg: 0
*.tabbed.tab-fg: 0
*.tabbed.tab-bg: 1
*.tabbed.tabbar-fg: 1
Choisir son jeu de couleur
--------------------------
Voici un lien sympa qui nous aide à choisir nos couleurs pour avoir des contrastes qui rendent l'interface
accessible : `terminal sexy <https://terminal.sexy/#DwoY0svhGRIlIxoyNipKUD9tcVqXk4C0ua7P5OHtda7C2rzJarecg8mwZ6SPuq3T0YSqcLOb>`_.
Notes
-----
Le copier coller se fait avec ``Ctrl+Alt+C`` et ``Ctrl+Alt+V``.

66
xorg/vscodium.rst Normal file
View File

@@ -0,0 +1,66 @@
..
Copyright (C) 2023 Jeremie Salvi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
Configuration de VSCodium
=========================
VSCodium est un fork de l'environnement de développement créé par windows, mais qui
suprime la télémétrie Microsoft, et remplace les quelques portions sous licence du
logiciel, comme l'icone et le logo par exemple. Il n'a malheureusement plus accès à
la bibliothèque en ligne d'extensions, il en utilise une alternative plutôt bien fournie,
mais certaines extensions devront ête téléchargées et installées à la main.
je vais documenter ici ma configuration, les astuces pour utliser l'environnement, et les
extensions générales que j'utilise. Pour celles propre à des projets ou des langages, je
le documenterai dans la section en conséquence.
Prérequis
---------
Codium est basé sur electron, il est donc multi-plateforme. Pour les prérequis, ils sont
listés sur `AUR (Arch User Repositories) <https://aur.archlinux.org/packages/vscodium-bin>`_.
Installation
------------
On l'installe comme n'importe quel paquet AUR :
.. code-block:: bash
cd /opt
git clone https://aur.archlinux.org/vscodium-bin.git
cd vscodium-bin/
makepkg
pacman -U vscodium-bin-1.72.2.22289-1-x86_64.pkg.tar.zst
Extensions
----------
Atom One Dark Theme
~~~~~~~~~~~~~~~~~~~
Un thème sombre mais avec des contrastes meilleurs que celui de base.
C'est le thème de base de l'éditeur Atom.
Il est dans le store, il suffit de tapper dark thème
.. image:: ../images/atom_dark_theme_extension.png
reStructuredText Syntax highlighting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Très pratique pour la documentation avec Sphinx. Disponible dans le store.
.. image:: ../images/reStructuredText_extension.png
emojisense
~~~~~~~~~~
Très pratique à utiliser avec sphinx pour agrémenter notre documentation de
petits emoji 😃. on lance l'intellisense avec ``Ctrl+i``.
.. image:: ../images/emoji_extension.png