2211 lines
96 KiB
Org Mode
2211 lines
96 KiB
Org Mode
# -*- eval: (require 'ox-hugo) -*-
|
||
#+title: Phundrak’s Blog
|
||
#+author: Lucien “Phundrak” Cartier-Tilet
|
||
#+hugo_base_dir: ../
|
||
#+hugo_section: ./
|
||
#+hugo_categories: emacs linux conlanging orgmode
|
||
#+startup: content
|
||
|
||
* [EN] Open-Sourcing ALYS :ALYS:
|
||
:PROPERTIES:
|
||
:EXPORT_FILE_NAME: open-sourcing-alys
|
||
:EXPORT_DATE: 2021-12-15
|
||
:export_hugo_menu: :menu "main"
|
||
:END:
|
||
#+TOC: headlines 1 local
|
||
|
||
** Too Long, Didn’t Read
|
||
VoxWave no longer exists as a company, ALYS lives on as an open-source
|
||
project under the GPL-3.0 and the BY-CC-4.0 license. You can find it
|
||
at the following address:
|
||
+[[https://labs.phundrak.com/phundrak/ALYS]]+
|
||
|
||
EDIT: The main repository moved to [[https://labs.phundrak.com/ALYS/ALYS]]
|
||
and vocal libraries are now separated in different repositories linked
|
||
from the main one.
|
||
|
||
** What happened?
|
||
You might have noticed it, but VoxWave became quite silent over the
|
||
last months. This is because we at the head of VoxWave chose to close
|
||
the company, a decision which came in effect in early September 2021.
|
||
There’s not much else to say.
|
||
*However*, the good news is the rest still goes on! ALYS as a project is
|
||
still alive and well! As her creator, I decided to step in and
|
||
continue its technical support. Since the company no longer exists,
|
||
and as a free and open-source software supporter, I also decided to
|
||
open-source ALYS as much as possible. As a result:
|
||
|
||
#+begin_center
|
||
ALYS for Alter/Ego is now free software as in /free beer/.
|
||
|
||
ALYS for UTAU, including its previously unreleased UTAU prototype, is
|
||
now free as in /free beer/ and in /freedom/.
|
||
#+end_center
|
||
|
||
You can find the installer of ALYS for Alter/Ego on the repository
|
||
linked above as well as a free license file. Regarding its UTAU
|
||
version, its prototype is already configured with ~oto.ini~ files, but
|
||
the source file for its Alter/Ego version are stripped of any
|
||
configuration.
|
||
|
||
** What’s New?
|
||
Therefore, ALYS is now available under three different licences:
|
||
- The character is now under the free [[https://creativecommons.org/licenses/by-nc/4.0/][CC-BY-NC-4.0 license]]
|
||
- The UTAU vocal libraries are now under the [[https://www.gnu.org/licenses/gpl-3.0.en.html][GPL-3.0license ]] ([[https://choosealicense.com/licenses/gpl-3.0/][short
|
||
readable version]])
|
||
- The Alter/Ego is still under a proprietary license under my name but
|
||
it is now available free of charge
|
||
|
||
Basically, this means you can do whatever you wish with the character
|
||
as long as it is non-commercial and you credit [[https://www.instagram.com/hsaphirya/][Saphirya]], ALYS’
|
||
designer. The UTAU vocal libraries can be used, modified, and
|
||
redistributed as much as you wish as long as it stays under the
|
||
GPL-3.0 license. And you are free to use the Alter/Ego vocal libraries
|
||
as much as you wish, but you cannot redistribute or modify them.
|
||
|
||
I also decided to release ALYS’ very first, secret, unreleased,
|
||
unheard French vocal library. It was scrapped no long after recording
|
||
it due to quality issues and was replaced by its French UTAU prototype
|
||
people could hear through ALYS’ first songs. It is released more as a
|
||
way of preserving the fact it existed rather preserving a usable vocal
|
||
library. (I don’t even remember what it sounds like.)
|
||
|
||
if you have any question, you are free to send me an email at
|
||
[[mailto:lucien@phundrak.com][lucien@phundrak.com]] or open an issue on the repository mentioned
|
||
above.
|
||
* Conlanging :@conlang:
|
||
** TODO Writing my conlanging docs with Emacs :emacs:conlanging:
|
||
* Development :@dev:
|
||
** [FR] Mettre à niveau mes sites org-mode :dev:emacs:
|
||
:PROPERTIES:
|
||
:EXPORT_FILE_NAME: mettre-a-nivea-mes-sites-org-mode
|
||
:EXPORT_DATE: 2022-08-15
|
||
:export_hugo_menu: :menu "main"
|
||
:END:
|
||
*** Le Problème
|
||
Cela fait quelques temps que je réfléchis à une nouvelle manière de
|
||
gérer deux de mes sites web, [[https://conlang.phundrak.com][conlang.phundrak.com]] et
|
||
[[https://config.phundrak.com][config.phundrak.com]].
|
||
|
||
Les deux sites sont actuellement générés via un export depuis org-mode
|
||
(un des nombreux modes d’Emacs) directement vers du HTML. Sauf que
|
||
l’organisation du fichier HTML de sortie de me plaît pas, et depuis
|
||
plus de deux ans j’utilise un script rédigé en Dart et compilé vers
|
||
Javascript pour réorganiser les fichiers. En soit ce ne serait pas
|
||
trop grave si mes pages web n’étaient pas forcément lourdes. Mais
|
||
elles le sont! La plus lourde page de mon site de linguistique fait
|
||
232Ko (la page francophone sur le Proto-Ñyqy) et celle de mon site de
|
||
configuration fait 5,5Mo (configuration Emacs) ! Je parle bien de
|
||
fichiers HTML ! Il faut vraiment que ça change!
|
||
|
||
*** Nouveau Framework pour le front-end
|
||
À la base je m’étais lancé pour écrire un exporteur personnalisé pour
|
||
exporter mes fichiers org-mode vers des fichiers JSX qui seraient
|
||
utilisés par un projet [[https://reactjs.org/][Reac]]t, ou même [[https://nextjs.org/][Next.js]]. Mais j’ai récemment
|
||
découvert quelque chose qui pourrait être bien plus pratique pour
|
||
moi : [[https://vuejs.org/][Vue]] et tout particulièrement [[https://v3.nuxtjs.org/][Nuxt]] !
|
||
|
||
En effet, Nuxt lit le [[https://content.nuxtjs.org/guide/writing/mdc/][MDC]], ou Markdown Components. De fait, il est
|
||
possible avec MDC et Nuxt d’insérer dans du Markdown des composants
|
||
Vue soit en blocs soit en inline. Et pour moi, ça change tout ! Je
|
||
peux maintenant écrire un exporteur minimal qui se chargera simplement
|
||
d’exporter quelques éléments personnalisés vers des composants Vue,
|
||
voire même de simples macros org-mode pour exporter les composants
|
||
inline.
|
||
|
||
Et bien sûr, pour pallier au problème de fichiers HTML trop lourds, il
|
||
me faudra séparer mes fichiers actuels en plusieurs fichiers, mais
|
||
cela devrait être plus simple à gérer une fois la transition vers le
|
||
nouveau framework effectuée.
|
||
|
||
*** Et pour le backend ?
|
||
Mais ce n’est pas tout : un élément que j’aimerais ajouter à mon site
|
||
de linguistique serait un dictionnaire entre mes langues construites
|
||
et d’autres langues, qu’elles soient construites ou non. Ce
|
||
dictionnaire doit pouvoir être interactif, avec par exemple une
|
||
recherche, une page par mot, etc.
|
||
|
||
Je ne ferai certainement pas télécharger à mes utilisateurs
|
||
l’entièreté du dictionnaire à chaque recherche d’un mot dans le
|
||
dictionnaire, il ne peut donc pas être hébergé avec mon frontend, et
|
||
j’aurai besoin d’un backend avec une API REST pour gérer les requêtes
|
||
des visiteurs du site web. Maintenant la question est, quel type de
|
||
back-end ?
|
||
|
||
Tout d’abord, je vais complexifier un peu le problème : je suis un
|
||
grand amateur de org-mode. Je pourrais gérer ça via une base de
|
||
données classique, ajoutant chaque entrée manuellement, mais je vais
|
||
plutôt essayer de gérer tout ça via org-mode. Les fichiers texte sont
|
||
plus simples à versionner que des bases de données en un seul fichier
|
||
binaire. Du coup, il va falloir que je m’écrive un nouvel exporter,
|
||
mais lequel ?
|
||
|
||
Je pourrais rédiger un exporteur pour mon fichier ~dictionnaire.org~ qui
|
||
l’exporterait vers un fichier Json qui serait lu ensuite par mon
|
||
backend qui extraierait et enverrai à mes utilisateurs les
|
||
informations nécessaires. L’avantage serait de n’avoir quasiment pas
|
||
besoin de manipuler le Json et d’en envoyer tel quel. Mais l’ouverture
|
||
et fermeture constante du fichier n’est pas forcément la meilleure des
|
||
idées, quoi que cela pourrait permettre de remplacer le fichier
|
||
pendant que le backend tourne. Mais je suis sûr qu’on peut mieux
|
||
faire.
|
||
|
||
Ma solution suivante était d’utiliser EmacSQL, un paquet Emacs lui
|
||
permettant d’interagir avec des bases de données SQLite, PostgreSQL et
|
||
MySQL. Au moins ce serait une véritable base de données, avec
|
||
seulement un blob binaire à mettre à jour, et ce serait
|
||
potentiellement plus performant étant donné qu’il n’y aura qu’à ouvrir
|
||
une fois une connexion avec elle. Mais le problème est maintenant sa
|
||
mise à jour. Mince…
|
||
|
||
Vient enfin ma troisième solution qui, je pense, sera celle que je
|
||
vais adopter : utiliser une base de donnée type Firebase. L’idée d’un
|
||
verrouillage fournisseur ne me plaît pas franchement, donc j’ai décidé
|
||
d’utiliser une alternative open source et hébergeable : [[https://appwrite.io/][Appwrite]]! Je
|
||
peux écrire sur une de ses bases de données pendant que mes
|
||
utilisateurs peuvent la lire, donc la mise à jour n’est pas un
|
||
problème, et je n’ai rien à mettre en ligne, seulement une série de
|
||
requêtes à faire. Cependant, un problème reste : comment communiquer
|
||
avec Appwrite?
|
||
|
||
*** La quête pour un SDK Appwrite pour Emacs
|
||
Hélas, j’ai beau chercher, il n’existe aucun paquet pour Emacs
|
||
permettant une communication avec Appwrite. Mais ce n’est pas
|
||
franchement surprenant : Appwrite n’est pas encore extrêmement
|
||
répandu, et même Firebase ne dispose pas de paquet pour Emacs.
|
||
|
||
Bien heureusement, Appwrite dispose d’une API REST assez bien
|
||
documentée, et Emacs est capable de gérer des requêtes nativement via
|
||
sa bibliothèque ~url~, c’est donc naturellement que j’ai commencé à
|
||
travailler sur ~appwrite.el~, un SDK Appwrite pour du Emacs Lisp.
|
||
J’aurais pu utiliser ~request.el~, un paquet assez populaire pour Emacs
|
||
afin de gérer les requêtes HTTP, mais je ne suis pas grand fan de son
|
||
workflow et je préfère limiter au maximum le nombre de dépendances
|
||
dans mes paquets. Ce que ce paquet fait actuellement est une
|
||
transformation des paramètres nommés que mes fonctions acceptent en un
|
||
payload Json. Par exemple, ma fonction ~appwrite-stogare-list-buckets~
|
||
accepte les mot-clefs ~search~, ~limit~, ~offset~, ~cursor~, ~cursor-direction~
|
||
et ~order-type~. Ces arguments sont transformés en du Json via la
|
||
bibliothèque native d’Emacs afin de donner ceci :
|
||
#+begin_src js
|
||
{
|
||
"search": "my search request",
|
||
"limit": 30,
|
||
"offset": 0,
|
||
"cursor": "",
|
||
"cursorDirection": "before",
|
||
"orderType": "ASC",
|
||
}
|
||
#+end_src
|
||
|
||
Ce payload Json est enfin envoyé à l’API REST correspondante, en
|
||
l’occurrence ~/v1/storage/buckets~ comme on peut le voir [[https://appwrite.io/docs/server/storage?sdk=nodejs-default#storageListBuckets][sur la
|
||
documentation officielle]]. Bien sûr, les éléments optionels ne sont
|
||
pas nécessairement inclus afin d’éviter à avoir à envoyer trop
|
||
d’informations. Dans ce cas, tous les éléments du payload sont
|
||
optionels, ce qui ferait que le ~appwrite.el~ n’enverra que src_js{{}}
|
||
comme payload à l’API.
|
||
|
||
Pour l’instant, le projet en est encore à ses débuts, mais j’ai
|
||
commencé à travailler sur le SDK pour Appwrite que vous pouvez trouver
|
||
sur [[https://github.com/Phundrak/appwrite.el][ce dépôt Github]].
|
||
|
||
La question maintenant est : comment exporter mon dictionnaire vers
|
||
Appwrite ? La réponse me semble relativement simple ; je pourrai
|
||
écrire un exporteur org-mode dépendant de ~appwrite.el~ qui exportera
|
||
pour chaque mot qu’il rencontrera un payload Json vers mon instance
|
||
personnelle Appwrite. Et à la différence des exporteurs org-mode
|
||
habituels, ~ox-appwrite~ n’exportera aucun fichier sur mon système.
|
||
|
||
*** Conclusions
|
||
Au fur et à mesure de mon analyse du projet et de mes besoins, je me
|
||
suis rendu compte que j’aurai besoin d’outils plus intelligents que de
|
||
simples pages HTML exportées automatiquement via Emacs.
|
||
|
||
Ainsi, j’aurai besoin de créer un site web avec Nuxt, profitant ainsi
|
||
de sa capacité à rendre du Markdown avec du contenu interactif,
|
||
agissant en tant que frontend pour mon site web. Ce Markdown sera
|
||
exporté via org-mode à partir de mes fichiers déjà existants, bien
|
||
qu’à fragmenter afin de réduire la taille des fichiers de sortie.
|
||
|
||
Le backend sera une instance Appwrite que j’hébergerai moi-même sur
|
||
mes serveurs. Elle sera populée par un exporter org-mode custom via
|
||
Emacs, ce qui me permettra de continuer à gérer mes dictionnaires et
|
||
mes langues avec org-mode.
|
||
|
||
Ce projet est vraiment intéressant car cela m’a incité à explorer de
|
||
nombreuses possibilités et technologies différentes afin de trouver ce
|
||
qui correspond le mieux à mon besoin, notamment en me rendant compte
|
||
par exemple que React n’était pas forcément l’outil le plus adapté à
|
||
ce projet précisément. Cela me fera également travailler sur ma
|
||
capacité à interagir avec des backends et des API REST, tout autant du
|
||
côté front-end pour le site web que du côté SDK avec Emacs. Enfin, la
|
||
création de ce SDK ainsi que des exporteurs org-mode me sera bénéfique
|
||
afin d’approfondir ma connaissance d’Emacs et du Emacs Lisp.
|
||
|
||
Maintenant, au travail !
|
||
|
||
** [EN] Writing a Dynamic Array in C :dev:C:
|
||
:PROPERTIES:
|
||
:EXPORT_FILE_NAME: writing-dynamic-vector-c
|
||
:EXPORT_DATE: 2020-11-28
|
||
:export_hugo_menu: :menu "main"
|
||
:END:
|
||
Although C is a very, very popular language, it is also known to be
|
||
quite tiny: memory is handled manually, and much of what is available
|
||
in its standard library is a given in all other languages. But C being
|
||
a low level language also means it lacks a lot of other stuff other
|
||
popular languages have; for instance, dynamic arrays are present in
|
||
the library of most popular languages, be it JavaScript, C++, Rust and
|
||
so on, but C’s simplicity forbids them from being there. If you want
|
||
it in C, you have to implement it –which is exactly what I did!
|
||
|
||
#+TOC: headlines 1 local
|
||
*** Introduction
|
||
When I wrote this library, I was mostly inspired by C++’s ~std::vector~
|
||
and Rust’s ~std::vec::Vec~, but my library lacks some features both
|
||
have: it’s still a simple one. Here is the list of what it is able to
|
||
do:
|
||
- Create a dynamic array, with or without an initial capacity
|
||
specified by the user
|
||
- Store a function pointer to the /destructor/ of the elements that will
|
||
be stored in the vector for when they are destroyed
|
||
- Append new elements at the end of the array
|
||
- Get elements by position, safely or not, or get the first and last
|
||
elements in the array
|
||
- Get the length of the vector as well as its capacity
|
||
- Shrink the size of the allocated array to the size of the vector
|
||
- Remove an element at a specific index, or the last element
|
||
- Completely destroy the vector and its elements
|
||
|
||
Elements that will be stored in the vector will need to be dynamically
|
||
allocated in memory since the vector will not store the elements
|
||
themselves, but rather pointers to them. This way, we avoid copying
|
||
data when inserting it to the vector, and handling these elements is
|
||
also a tad easier. And since we do not know what we will be storing,
|
||
we will be storing void pointers. The user will be able to cast them
|
||
to their desired type later on.
|
||
|
||
Before defining the vector, there are a few things I want to define.
|
||
First, there is an attribute I will often use with my functions:
|
||
#+NAME: vector-nonnull-h
|
||
#+BEGIN_SRC c
|
||
#indef NONNULL
|
||
# define NONNULL __attribute__((nonnull))
|
||
#endif
|
||
#+END_SRC
|
||
This will forbid passing to functions marked with this attribute ~NULL~
|
||
pointers, because we will use a lot of them.
|
||
|
||
We will also need to include some headers:
|
||
- ~assert.h~ :: so we can make sure memory is allocated and reallocated
|
||
correctly
|
||
- ~string.h~ :: for some memory operations such as ~memcpy~
|
||
#+NAME: vector-includes-c
|
||
#+BEGIN_SRC c
|
||
#include <assert.h>
|
||
#include <string.h>
|
||
#+END_SRC
|
||
|
||
We also need to define a type that will be used as the destructor
|
||
type. The functions we want to accept as destructors are functions
|
||
that accept a void pointer to an element and return nothing, hence
|
||
this definition:
|
||
#+NAME: vector-destructor-type-h
|
||
#+BEGIN_SRC c
|
||
typedef void (*Destructor)(void *element);
|
||
#+END_SRC
|
||
|
||
Now, onto the structure itself.
|
||
|
||
*** The Data Structure of the Vector
|
||
With our vector, we will need to keep track a couple of things:
|
||
- the size of the vector
|
||
- the capacity of the vector
|
||
- the destructor
|
||
- the array itself
|
||
With this, we can describe our structure for the vector:
|
||
#+NAME: vector-struct-def
|
||
#+BEGIN_SRC c
|
||
struct Vector_s {
|
||
size_t capacity;
|
||
size_t length;
|
||
void ** elements;
|
||
Destructor destructor;
|
||
};
|
||
typedef struct Vector_s Vector;
|
||
#+END_SRC
|
||
|
||
We have now four elements:
|
||
- ~elements~ :: an array of void pointers pointing themselves either to
|
||
elements stored in the vector or to nothing (initialized to ~NULL~)
|
||
(note this forbids storing ~NULL~ elements in the vector),
|
||
- ~length~ :: the number of elements currently stored in the vector,
|
||
- ~capacity~ :: the size of the allocated memory pointed to by ~elements~
|
||
divided by the size of a void pointer. This gives us the amount of
|
||
elements that can be stored in the vector without any reallocation /at most/,
|
||
- ~destructor~ :: pointer to the function used to free elements stored
|
||
in the vector
|
||
|
||
Now, onto the functions associated with this data structure. They are
|
||
all prefixed with ~vec_~ in order to avoid any collisions with other
|
||
libraries and functions.
|
||
|
||
*** Building Vectors
|
||
The first function for building vectors is ~vec_new()~. Here is its
|
||
definition:
|
||
#+NAME: vector-vec_new-h
|
||
#+BEGIN_SRC c
|
||
Vector *vec_new(Destructor const destructor);
|
||
#+END_SRC
|
||
|
||
It is quite straightforward: when creating a new, standard vector,
|
||
simply pass as its arguments a pointer to the destructor of this
|
||
vector, either a ~NULL~ pointer for trivial data types, or a pointer to
|
||
an existing function you declared somewhere. Once you do that, you get
|
||
yourself a pointer to the newly created vector with which you can now
|
||
store elements. Let’s see how it works under the hood:
|
||
#+NAME: vector-vec_new-c
|
||
#+BEGIN_SRC c
|
||
Vector *vec_new(Destructor const destructor)
|
||
{
|
||
Vector *self;
|
||
self = (Vector *)malloc(sizeof(Vector));
|
||
assert(self);
|
||
,*self = (Vector){.length = 0,
|
||
.capacity = VEC_INITIAL_CAPACITY,
|
||
.elements = (void *)malloc(sizeof(void *) * VEC_INITIAL_CAPACITY),
|
||
.destroy = destructor};
|
||
assert(self->elements);
|
||
return self;
|
||
}
|
||
#+END_SRC
|
||
|
||
A new pointer is created, which will be the pointer returned to the
|
||
user. To this pointer, we allocate enough memory to hold a vector.
|
||
Once that is done, we initialize this new memory buffer with an actual
|
||
vector, with its members initialized as described above. An assertion
|
||
is done in order to ensure both the vector but also its storage are
|
||
correctly allocated.
|
||
|
||
The second function, ~vec_with_capacity~, is quite similar though not
|
||
the same as ~vec_new~: it allows for an initialization of
|
||
~vec_with_capacity~ with a user-defined amount of capacity in the
|
||
storage of the vector. That is, if ~vec_with_capacity(14)~ is called,
|
||
the library will return a pointer to a vector which can contain and
|
||
has the size of precisely fourteen elements. That way, if the user
|
||
knows they’ll need a certain amount of elements to be stored in a
|
||
vector, they’ll be able to reserve that exactly and limit the amount
|
||
of reallocations when adding new elements. Its definition is the
|
||
following:
|
||
#+NAME: vector-vec_with_capacity-h
|
||
#+BEGIN_SRC c
|
||
Vector *vec_with_capacity(Destructor const destructor, size_t const capacity);
|
||
#+END_SRC
|
||
|
||
Under the hood, it calls ~vec_new~, then it will reallocate the memory
|
||
already allocated for the member ~elemements~.
|
||
#+NAME: vector-vec_with_capacity-c
|
||
#+BEGIN_SRC c
|
||
Vector *vec_with_capacity(Destructor const t_destructor,
|
||
size_t const t_capacity)
|
||
{
|
||
Vector *self = vec_new(t_destructor);
|
||
free(self->elements);
|
||
(*self).elements = (void *)malloc(sizeof(void *) * t_capacity);
|
||
assert(self->elements);
|
||
(*self).capacity = t_capacity;
|
||
return self;
|
||
}
|
||
#+END_SRC
|
||
|
||
*** Adding Data
|
||
The main feature of vectors is to hold data, so let’s make them able
|
||
to take new data from the user. But first, let me explain a bit how
|
||
this dynamic array which I call vector works in C.
|
||
|
||
As you saw earlier, a vector is initialized with a fixed amount of
|
||
memory allocated to the vector so people can store their data in these
|
||
arrays. Now, imagine you have an array of four elements and you wish
|
||
to add one more, what to do? You can reallocate your array with
|
||
~realloc~ with one more slot for your element, so now you have an array
|
||
for five elements with your four original elements an a free slot for
|
||
your fifth. Cool, now you can add new elements as you need them!
|
||
|
||
Except that if you want to add some tens of thousands of new elements,
|
||
you would end up calling some tens of thousands times ~realloc~, and
|
||
that is /*slow*/. Seriously, try it, you’ll understand what I mean. And
|
||
all these calls to ~realloc~ are an opportunity for it to fail. Let’s
|
||
limit calls to this function, OK ? If we end up short on slots in our
|
||
current array, let’s actually double the amount of slots in it. So, if
|
||
we have a four-slots array, let’s make it an eight-slots array, and
|
||
then a sixteen-slots array. And in a couple more calls to ~realloc~,
|
||
we’ll quickly reach our tens of thousands slots array, way faster than
|
||
by incrementing its capacity one by one.
|
||
/“But, we’ll end up with a lot of unused memory if we need just one more element than 2^{16} elements! We don’t need a 2^{32} elements array for 2^{16}+1 elements!”/
|
||
|
||
You’re completely right, but that’s a tradeoff. Would you rather have
|
||
a slow but memory-efficient program, or a fast but memory-hungry
|
||
software? Plus, as you’ll see later, there is a function to shrink the
|
||
size of the allocated array down to the actual amount of elements you
|
||
stored in it, making it possible to temporarily have a 2^{32} elements
|
||
array, and immediately after shrink it down to 2^{16}+1, once you know
|
||
you won’t be adding any other elements.
|
||
|
||
With this out of the way, let’s see how to add new elements to our
|
||
vector. First, let’s declare a static function that reallocates the
|
||
memory of a vector. Here is its declaration:
|
||
#+NAME: vector-vec_realloc-def-c
|
||
#+BEGIN_SRC c
|
||
static void vec_realloc(Vector *const self) NONNULL;
|
||
#+END_SRC
|
||
|
||
Its implementation is rather simple: double its capacity, and
|
||
reallocate its array twice its previous size. Of course, there is an
|
||
assertion on whether the arrays has been correctly reallocated to
|
||
ensure memory safety.
|
||
#+NAME: vector-vec_realloc-c
|
||
#+BEGIN_SRC c
|
||
void vec_realloc(Vector *const self)
|
||
{
|
||
self->capacity *= 2;
|
||
self->elements = realloc(self->elements, sizeof(void *) * vec_capacity(self));
|
||
assert(self->elements);
|
||
return;
|
||
}
|
||
#+END_SRC
|
||
|
||
Now, we can proceed to element insertion. Here is the definition of
|
||
~vec_push~, which adds a new element at the end of the vector:
|
||
#+NAME: vector-vec_push-h
|
||
#+BEGIN_SRC c
|
||
void *vec_push(Vector *const self, void *const element) NONNULL;
|
||
#+END_SRC
|
||
|
||
As you can see, it takes as its arguments a pointer to the vector (the
|
||
same returned by its constructor) as well as a pointer to the element
|
||
to be added to the vector. This is an important point: *the vector does
|
||
not store elements themselves, only their pointer*. If the function
|
||
detects there is not enough space for a new element, a call will be
|
||
made to ~vec_realloc~ described above. Once the function is done, it
|
||
will return a pointer to the newly inserted element.
|
||
#+NAME: vector-vec_push-c
|
||
#+BEGIN_SRC c
|
||
void *vec_push(Vector *const self, void *const t_element)
|
||
{
|
||
if (vec_length(self) >= vec_capacity(self)) {
|
||
vec_realloc(self);
|
||
}
|
||
self->elements[(*self).length++] = t_element;
|
||
return vec_last(self);
|
||
}
|
||
#+END_SRC
|
||
|
||
And this is it! There may be a function added later that will allow
|
||
the insertion of a new value in any valid position between the first
|
||
and last position of an array (not counting the unused slots of said
|
||
array), and if I implement this it will imply a reimplementation of
|
||
~vec_push~ so that ~vec_push~ relies of this potential new ~vec_insert~.
|
||
|
||
*** Retrieving Data
|
||
Two functions are available when retrieving data: ~vec_safe_at~ which
|
||
safely retrieves the element at a certain index, and ~vec_at~, which is
|
||
a bit more performant but without the safety of the former. Let’s see
|
||
the definition of both:
|
||
#+NAME: vector-vec_at-h
|
||
#+BEGIN_SRC c
|
||
void *vec_safe_at(Vector const *const self, size_t const index) NONNULL;
|
||
void *vec_at(Vector const *const self, size_t const index) NONNULL;
|
||
#+END_SRC
|
||
|
||
Both have the same arguments: the former is a pointer to the vector we
|
||
want to manipulate, and the latter is the index at which we want to
|
||
retrieve our data. To see the difference in how both work, let’s first
|
||
see the definition of ~vec_at~:
|
||
#+NAME: vector-vec_at-c
|
||
#+BEGIN_SRC c
|
||
void *vec_at(Vector const *const self, size_t const index)
|
||
{
|
||
return self->elements[index];
|
||
}
|
||
#+END_SRC
|
||
~vec_at~ is really straightforward and is just syntax sugar around the
|
||
vector’s ~elements~ member and will behave exactly like the square
|
||
brackets in standard C. However, ~vec_safe_at~ performs some additional
|
||
checks as you can see below:
|
||
#+NAME: vector-vec_safe_at-c
|
||
#+BEGIN_SRC c
|
||
void *vec_safe_at(Vector const *const self, size_t const t_index)
|
||
{
|
||
return (t_index >= vec_length(self)) ? NULL : vec_at(self, t_index);
|
||
}
|
||
#+END_SRC
|
||
|
||
If the requested index is larger than the furthest index possible, a
|
||
~NULL~ pointer will be returned, otherwise the pointer to the requested
|
||
element is. With this function, it is possible to check whether an
|
||
element has been returned or not while avoiding a possible segfault or
|
||
something similar. It could be used in a loop for instance in order to
|
||
check we only have valid elements.
|
||
|
||
It is also possible to retrieve directly the last element with
|
||
~vec_last~. Here is its definition:
|
||
#+NAME: vector-vec_last-h
|
||
#+BEGIN_SRC c
|
||
void *vec_last(Vector const *const self) NONNULL;
|
||
#+END_SRC
|
||
|
||
Just as the previous functions, its declaration is really straightforward:
|
||
#+NAME: vector-vec_last-c
|
||
#+BEGIN_SRC c
|
||
void *vec_last(Vector const *const self)
|
||
{
|
||
return vec_at(self, vec_length(self) - 1);
|
||
}
|
||
#+END_SRC
|
||
|
||
For the sake of the Object Oriented Programming paradigm, two
|
||
functions were also declared in order to retrieve some data that could
|
||
otherwise be easily accessible:
|
||
#+NAME: vector-vec_length_capacity-h
|
||
#+BEGIN_SRC c
|
||
size_t vec_length(Vector const *const self) NONNULL;
|
||
size_t vec_capacity(Vector const *const self) NONNULL;
|
||
#+END_SRC
|
||
|
||
Their implementation is extremely trivial and doesn’t really need any
|
||
explanation.
|
||
#+NAME: vector-vec_length_capacity-c
|
||
#+BEGIN_SRC c
|
||
size_t vec_length(Vector const *const self)
|
||
{
|
||
return self->length;
|
||
}
|
||
|
||
size_t vec_capacity(Vector const *const self)
|
||
{
|
||
return self->capacity;
|
||
}
|
||
#+END_SRC
|
||
|
||
*** Deleting Data
|
||
While this chapter is about destroying data, this first function will
|
||
not exactly destroy data, or at least not data we care about:
|
||
~vec_shrink_to_fit~ will reallocate the memory in our vector to make it
|
||
so that the member ~elements~ is exactly large enough to store all of
|
||
our data with no more space than that. Here is its definition:
|
||
#+NAME: vector-shrink_to_fit-h
|
||
#+BEGIN_SRC c
|
||
void vec_shrink_to_fit(Vector *const self) NONNULL;
|
||
#+END_SRC
|
||
|
||
There’s nothing too exciting about its implementation: a simple
|
||
reallocation exactly the size of the number of elements currently
|
||
stored times the size of a void pointer, and we verify with an ~assert~
|
||
if it has been correctly reallocated. Nothing is returned.
|
||
#+NAME: vector-shrink_to_fit-c
|
||
#+BEGIN_SRC c
|
||
void vec_shrink_to_fit(Vector *const self)
|
||
{
|
||
if (self->length <= 0) {
|
||
return;
|
||
}
|
||
self->capacity = self->length;
|
||
self->elements = realloc(self->elements, sizeof(void *) * vec_capacity(self));
|
||
assert(self->elements);
|
||
return;
|
||
}
|
||
#+END_SRC
|
||
|
||
Notice that a check is done to see if the vector exists, because
|
||
otherwise calling ~shrink_to_fit~ on an empty vector would result in an
|
||
error while asserting the reallocation.
|
||
|
||
Next, we have two functions: ~vec_pop_at~ and ~vec_pop~. The latter relies
|
||
on the former, which can delete an element at any valid position.
|
||
*Beware*: these functions return /nothing/ and simply deletes the element.
|
||
Here is their definition:
|
||
#+NAME: vector-vec_pop-h
|
||
#+BEGIN_SRC c
|
||
void vec_pop_at(Vector *const self, size_t const index) NONNULL;
|
||
void vec_pop(Vector *const self) NONNULL;
|
||
#+END_SRC
|
||
|
||
In order to insure memory safety, a static function is declared in
|
||
~src/vector.c~ which will delete an element if a destructor has been
|
||
provided to the vector when it has been built. Its definition is the
|
||
following:
|
||
#+NAME: vector-vec_maybe_delete_element-def-c
|
||
#+BEGIN_SRC c
|
||
static void vec_maybe_delete_element(Vector const *self,
|
||
size_t const t_index) NONNULL;
|
||
#+END_SRC
|
||
|
||
Its implementation is quite simple: if a destructor exists, then the
|
||
element at the requested index will be destroyed through this
|
||
destructor. Otherwise, nothing is done with the destructor, hence the
|
||
name of the function ~vec_maybe_delete_element~. However it should be
|
||
noted that the element will be freed from memory, so if the user needs
|
||
it before popping it, they need to retrieve it with something like
|
||
~vec_at~ and store it elsewhere.
|
||
#+NAME: vector-vec_maybe_delete_element-c
|
||
#+BEGIN_SRC c
|
||
void vec_maybe_delete_element(Vector const *self, size_t const t_index)
|
||
{
|
||
void *element = vec_at(self, t_index);
|
||
if (self->destroy) {
|
||
self->destroy(element);
|
||
}
|
||
free(element);
|
||
}
|
||
#+END_SRC
|
||
|
||
Now that we have this function sorted out, we can implement our pops.
|
||
Here is the implementation of ~vec_pop_at~:
|
||
#+NAME: vector-vec_pop_at-c
|
||
#+BEGIN_SRC c
|
||
void vec_pop_at(Vector *const t_self, size_t const t_index)
|
||
{
|
||
if (vec_safe_at(t_self, t_index) == NULL) {
|
||
return;
|
||
}
|
||
vec_maybe_delete_element(t_self, t_index);
|
||
if (t_index + 1 < vec_length(t_self)) {
|
||
memcpy(vec_at(t_self, t_index), vec_at(t_self, t_index + 1),
|
||
sizeof(void *) * (t_self->length - (t_index + 1)));
|
||
}
|
||
--(*t_self).length;
|
||
}
|
||
#+END_SRC
|
||
|
||
A check is performed at the beninning of the function: that the
|
||
element we want to pop actually exists. If it does not, the function
|
||
does nothing, otherwise the function deletes the element if needed.
|
||
The call to ~vec_maybe_delete_element~ will free the requested element.
|
||
Then, a check is performed to see if the requested element was at the
|
||
end of the array or not. If it was not, then the elements located
|
||
after the destroyed element are shifted one element closer to the
|
||
beginning of the array; otherwise, if the requested element was at the
|
||
end of the array, nothing is done particularly. Lastly, the count of
|
||
elements stored in the vector is decreased by one.
|
||
~vec_pop~ uses the above function in order to provide a simpler call if
|
||
we want to delete the last element of the array. We can see how it
|
||
relies on ~vec_pop_at~ in its implementation:
|
||
#+NAME: vector-vec_pop-c
|
||
#+BEGIN_SRC c
|
||
void vec_pop(Vector *const self)
|
||
{
|
||
vec_pop_at(self, vec_length(self));
|
||
}
|
||
#+END_SRC
|
||
|
||
Finally, ~vec_delete~ allows for the complete destruction and
|
||
deallocation of a vector, including all of its elements. Here is its
|
||
definition:
|
||
#+NAME: vector-vec_delete-h
|
||
#+BEGIN_SRC c
|
||
void vec_delete(Vector *const self) NONNULL;
|
||
#+END_SRC
|
||
|
||
In its implementation, we can see three distinct steps:
|
||
- The deletion of all its elements if a destructor exists
|
||
- The deletion of the array of the vector
|
||
- The deletion of the vector itself.
|
||
#+NAME: vector-vec_delete-c
|
||
#+BEGIN_SRC c
|
||
void vec_delete(Vector *const self)
|
||
{
|
||
if (self->destroy) {
|
||
for (size_t i = 0; i < vec_length(self); ++i) {
|
||
self->destroy(self->elements[i]);
|
||
}
|
||
}
|
||
free(self->elements);
|
||
free(self);
|
||
}
|
||
#+END_SRC
|
||
|
||
*** The Final Source Code
|
||
Finally, we can see the whole source code. Here is the header for the
|
||
library: ~vector.h~
|
||
#+BEGIN_SRC c :noweb yes
|
||
#ifndef VECTOR_H_
|
||
#define VECTOR_H_
|
||
|
||
<<vector-nonnull-h>>
|
||
|
||
<<vector-struct-def>>
|
||
|
||
<<vector-vec_new-h>>
|
||
<<vector-vec_with_capacity-h>>
|
||
<<vector-vec_push-h>>
|
||
<<vector-vec_at-h>>
|
||
<<vector-vec_last-h>>
|
||
<<vector-vec_length_capacity-h>>
|
||
<<vector-shrink_to_fit-h>>
|
||
<<vector-vec_pop-h>>
|
||
<<vector-vec_delete-h>>
|
||
|
||
#endif /* VECTOR_H_ */
|
||
#+END_SRC
|
||
|
||
And here is the implementation file: ~vector.c~
|
||
#+BEGIN_SRC c :noweb yes
|
||
#include "vector.h"
|
||
|
||
<<vector-includes-c>>
|
||
|
||
<<vector-vec_realloc-def-c>>
|
||
<<vector-vec_maybe_delete_element-def-c>>
|
||
|
||
<<vector-vec_new-c>>
|
||
|
||
<<vector-vec_with_capacity-c>>
|
||
|
||
<<vector-vec_realloc-c>>
|
||
|
||
<<vector-vec_push-c>>
|
||
|
||
<<vector-vec_at-c>>
|
||
|
||
<<vector-vec_safe_at-c>>
|
||
|
||
<<vector-vec_last-c>>
|
||
|
||
<<vector-vec_length_capacity-c>>
|
||
|
||
<<vector-shrink_to_fit-c>>
|
||
|
||
<<vector-vec_pop-c>>
|
||
|
||
<<vector-vec_maybe_delete_element-c>>
|
||
|
||
<<vector-vec_pop_at-c>>
|
||
|
||
<<vector-vec_pop-c>>
|
||
|
||
<<vector-vec_delete-c>>
|
||
#+END_SRC
|
||
|
||
And with that, we should be good! I used this library in a SOM
|
||
(Kohonen, 1982) implementation and ran it through valgrind, and there
|
||
were no memory leaks. If you find one though, don’t hesitate telling
|
||
me in the comments, through social media such as Twitter, or by email.
|
||
|
||
Happy programming!
|
||
|
||
* Emacs :@emacs:
|
||
** Emacs 29 is nigh! What can we expect? :dev:emacs:
|
||
:PROPERTIES:
|
||
:EXPORT_FILE_NAME: emacs-29-what-can-we-expect
|
||
:EXPORT_DATE: 2022-11-29
|
||
:export_hugo_menu: :menu "main"
|
||
:END:
|
||
It [[https://lists.gnu.org/archive/html/emacs-devel/2022-11/msg01774.html][was announced a couple of hours ago]], Emacs 29’s branch is now cut
|
||
from the master branch! This means the ~emacs-29~ branch will from now
|
||
no longer receive any new feature, but only bug fixes.
|
||
|
||
So, what’s new with this new major release? I skimmed over the ~NEWS~
|
||
file, and here are the changes which I find interesting and even
|
||
exciting for some.
|
||
*Article updated on November 30th at 13:15 UTC*
|
||
|
||
*** Major features
|
||
A couple of major improvements will be most likely present, here are
|
||
the ones that stand out the most for me.
|
||
|
||
**** Eglot is now part of Emacs core
|
||
During the last couple of years, LSP has given text editors incredible
|
||
capabilities, giving them IDE-like features relatively easily. Aside
|
||
from Elisp development, most of the code I write is now done with the
|
||
help of an LSP server, running along Emacs and analyzing my code,
|
||
suggesting and performing changes and actions for me.
|
||
|
||
Several integrations of LSP exist for Emacs, such as [[https://emacs-lsp.github.io/lsp-mode/][LSP Mode]], [[https://github.com/joaotavora/eglot][Eglot]],
|
||
and [[https://github.com/manateelazycat/lsp-bridge][lsp-bridge]]. Among the three, Eglot is now part of Emacs core! No
|
||
longer do you need to install a package, simply register an LSP server
|
||
and autocompletion, documentation, error detection, and other features
|
||
will become available right away!
|
||
|
||
I must admit I don’t really know Eglot, I personally use LSP Mode, but
|
||
with this addition to Emacs core, I might attempt the switch.
|
||
|
||
**** Tree-Sitter is also part of Emacs core
|
||
In case you didn’t know, Emacs’ current syntax highlighting is
|
||
currently based on a system of regexes. Although it is not the /worst/
|
||
thing to use, it’s not the best either, and it can become quite slow
|
||
on larger files.
|
||
|
||
Tree-Sitter parses programming languages based into a concrete syntax
|
||
tree. From there, not only can syntax highlighting can be done at high
|
||
speed, but a much deeper analysis of the code is possible and actions
|
||
such as syntax manipulation can also be achieved since the syntax tree
|
||
itself is available as an object which can be manipulated!
|
||
|
||
In case you want some more information on Tree-Sitter itself, you can
|
||
check out the [[https://tree-sitter.github.io/tree-sitter/][official Tree-Sitter website]], or you can even check this
|
||
talk out given by Tree-Sitter’s creator, Max Brunsfeld.
|
||
|
||
#+begin_export html
|
||
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/Jes3bD6P0To" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||
#+end_export
|
||
|
||
Well, this is now a native solution in Emacs! Currently, Emacs’
|
||
Tree-Sitter supports the current major modes :
|
||
- ~bash-ts-mode~
|
||
- ~c-ts-mode~
|
||
- ~c++-ts-mode~
|
||
- ~csharp-ts-mode~
|
||
- ~css-ts-mode~
|
||
- ~java-ts-mode~
|
||
- ~js-ts-mode~
|
||
- ~json-ts-mode~
|
||
- ~python-ts-mode~
|
||
- ~typescript-ts-mode~
|
||
|
||
Tree-Sitter also holds for now a special status in the new ~emacs-29~
|
||
branch since new features can still be added to it, as its merging
|
||
with the master branch is still recent. So we might see the list of
|
||
major modes for Emacs get a bit longer yet, especially considering
|
||
Tree-Sitter tries to make adding new languages relatively easy.
|
||
|
||
If you can’t wait to test Tree-Sitter, there is already [[https://emacs-tree-sitter.github.io/][another package]]
|
||
available for Emacs you can use right now. Just be aware this is not
|
||
the same package as the one that got integrated into Emacs.
|
||
|
||
**** Install packages from source with ~package.el~
|
||
If you use [[https://github.com/radian-software/straight.el][Straight]], you might be familiar with installing packages
|
||
directly from their Git repository. Well, good news, it is now
|
||
possible to install packages from Git using Emacs’ built-in packaging
|
||
system ~package.el~! It can be done with the new function
|
||
~package-vc-install~, and packages installed that way can be updated
|
||
with ~package-vc-update~ or ~package-vc-update-all~.
|
||
|
||
On the topic of ~package.el~, there is also the new function
|
||
~package-report-bug~ which allows Emacs users to report bugs to the
|
||
developers of a package directly from Emacs! Be aware though, it only
|
||
works for packages installed through ~package.el~. Since I’m a
|
||
[[https://github.com/jwiegley/use-package][~use-package~]] and ~straight.el~ user, there is no package listed when I
|
||
invoke the command.
|
||
|
||
**** Org mode 9.6
|
||
|
||
As confirmed by one of org-mode maintainers [[https://bzg.fr/][Bastien Guerry]] on [[https://lists.sr.ht/~bzg/emacsfr/%3C87bkophdzo.fsf%40phundrak.com%3E#%3C87tu2hqf4h.fsf@gnu.org%3E][a
|
||
French-speaking Emacs mailing list]], Org 9.6 is set to be part of
|
||
Emacs 29! I may try to write an article on this new release too, which
|
||
is [[https://elpa.gnu.org/packages/org.html][already available on GNU ELPA]]!
|
||
|
||
**** use-package in Emacs core
|
||
It has also been confirmed on the [[https://lists.gnu.org/archive/html/emacs-devel/2022-11/msg01821.html][Emacs development mailing list]] that
|
||
[[https://github.com/jwiegley/use-package][~use-package~]], an awesome package manager, is set to be part of Emacs
|
||
29, although it initially wasn’t included in the ~emacs-29~ branch.
|
||
|
||
**** Pure GTK Emacs is here for Wayland!
|
||
One of the major issues Emacs had on Linux was its dependency on Xorg
|
||
when running in GUI mode. When running Xorg, it’s not really an issue,
|
||
but Wayland has become more and more common during the last years, and
|
||
even with the existence of XWayland, this became an annoyance.
|
||
|
||
Well, fear not, for pure GTK Emacs is here! It can now be built
|
||
Xorg-free and run natively in Wayland!
|
||
|
||
Be aware though that Wayland is basically the only use-case for pure
|
||
GTK Emacs. If you don’t use Wayland, Emacs will display a warning
|
||
message, as it will most likely cause issues if you are running Xorg.
|
||
In my case, I sometimes see some ghost text when the content of a
|
||
buffer updates (I still need pure GTK though, since I alternate
|
||
between Xorg and Wayland).
|
||
|
||
**** Compile EmacsLisp files ahead of time
|
||
With Emacs 28 came the ability to natively compile EmacsLisp if your
|
||
Emacs was built with the ability to do so, using GCC’s Just In Time
|
||
library. This results in quite the impressive boost in performance,
|
||
which made Emacs much snappier than it was before. The only issue I
|
||
had was Emacs would only compile its EmacsLisp files when they were
|
||
loaded for the first time.
|
||
|
||
This is no longer the case! If you now compile Emacs with
|
||
~--with-native-compilation=aot~, Emacs’ native EmacsLisp files will be
|
||
natively compiled along with Emacs itself! Be aware though, it can be
|
||
slow on most machines, so the time you save by not compiling these
|
||
files when launching Emacs for the first time is basically transferred
|
||
to when compiling Emacs itself. Is it worth your time? In my case, I
|
||
would say yes, because when I compile Emacs, I’m generally not in a
|
||
hurry. But in your case? Well, test it out and see for yourself.
|
||
|
||
**** Native access to SQLite databases
|
||
Emacs can now be built with native support for SQLite and the sqlite3
|
||
library. In fact, this is now a default behaviour, since you need to
|
||
pass ~--without-sqlite3~ to Emacs’ build configuration script in order
|
||
to prevent it.
|
||
|
||
This comes with a new ~sqlite-mode~ which allows you to explore SQLite
|
||
databases within Emacs and to interact with them. Check out the
|
||
~sqlite-mode-open-file~ function!
|
||
|
||
**** HaikuOS support
|
||
For all three HaikuOS users out there, good news, you now have access
|
||
to Emacs! (In all seriousness, I should check out HaikuOS one day)
|
||
|
||
Moreover, it also supports an optional window-system port to Haiku
|
||
with ~--with-be-app~. Be aware, you will need the Haiku Application Kit
|
||
development headers and a C++ compiler. Otherwise, Emacs will only run
|
||
in the terminal. If you want to also add Cairo to the mix, you can add
|
||
~--with-be-cairo~.
|
||
|
||
**** New major mode for C#
|
||
~csharp-mode~ is now a native major mode for Emacs and is based on ~cc-mode~.
|
||
|
||
*** Minor features
|
||
**** It’s easier to use Emacs in scripts!
|
||
If you like to write scripts and especially writing Lisp scripts,
|
||
Emacs now supports the option ~-x~ in order to execute scripts written
|
||
in EmacsLisp. When executing such a script with ~#!/usr/bin/emacs -x~ as
|
||
its shebang, Emacs will not read its init file (like with ~-Q~) and will
|
||
instead execute the Elisp code right away and return the last value to
|
||
the caller of the script (most likely the shell you called the script
|
||
from).
|
||
|
||
**** TRAMP natively supports Docker, Podman, and Kubernetes
|
||
Three new connections are now available for TRAMP:
|
||
- ~docker~
|
||
- ~podman~
|
||
- ~kubernetes~
|
||
You will now be able to access your containerized environment right
|
||
from Emacs without the need to write custom code.
|
||
|
||
**** Custom user directory
|
||
It is now easier to launch custom Emacs profiles without the need of
|
||
tools such as [[https://github.com/plexus/chemacs2][chemacs2]] with the addition of the flag ~--init-directory~.
|
||
This can set to any directory Emacs’ ~user-emacs-directory~ which
|
||
includes the ~init.el~ which comes along with it. Yet another reason for
|
||
me not to use a ~.emacs~ file, but the ~init.el~ file instead.
|
||
|
||
**** Support for Webp images
|
||
For quite some time, Emacs has been able to display images, but not
|
||
webp yet. Well, this is now fixed! And in fact, support for webp
|
||
images became the default behaviour, since you need to pass
|
||
~--without-webp~ to Emacs’ configuration script to disable webp support.
|
||
|
||
**** C++ mode now supports the C++20 standard
|
||
Yep. There’s nothing more to say, really. Happy coding!
|
||
|
||
**** Better handling of ~.pdmp~ files
|
||
Emacs has had for a few version the ability to dump its state into a
|
||
~pdmp~ file for faster startup time. Well now, when creating such a
|
||
file, it will include in its name a fingerprint of its current state,
|
||
although it will still prioritize an ~emacs.pdmp~ file if it exists.
|
||
|
||
**** Better mouse and touchpad support
|
||
Emacs now uses XInput 2, which enables Emacs to support more input
|
||
events, such as touchpad events. For instance, by default, a pinch
|
||
gesture on a touchpad increases or decreases the text size of the
|
||
current buffer. This is thanks to the new event ~pinch~, which comes
|
||
along with ~touch-end~.
|
||
|
||
**** Unicode 15.0 and emojis
|
||
Emacs now supports [[https://www.unicode.org/versions/Unicode15.0.0/][Unicode 15.0]], which is currently the latest Unicode
|
||
version. Although this is not directly related, quite a few new
|
||
emoji-related features have been introduced. The new prefix ~C-x 8 e~
|
||
now leads to a few new commands related to emojis:
|
||
- ~C-x 8 e e~ or ~C-x 8 e i~ :: Insert an emoji (~emoji-insert~)
|
||
- ~C-x 8 e s~ :: Search an emoji (~emoji-search~)
|
||
- ~C-x 8 e l~ :: List all emojis in a new buffer (~emoji-list~)
|
||
- ~C-x 8 e r~ :: Insert a recently inserted emoji (~emoji-recent~)
|
||
- ~C-x 8 e d~ :: Describe an emoji (~emoji-describe~)
|
||
- ~C-x 8 e +~ and ~C-x 8 e -~ :: Increase and decrease the size of any
|
||
character, but especially emojis (~emoji-zoom-increase~ and ~emoji-zoom-decrease~ respectively)
|
||
|
||
There is also the new input method ~emoji~ which allows you to type for
|
||
instance ~:grin:~ in order to get the emoji 😁.
|
||
|
||
**** True background transparency
|
||
Up until recently, if you wanted transparency with Emacs, you had no
|
||
choice but to make the whole frame transparent, including text and
|
||
images.
|
||
|
||
Thanks to the frame parameter ~alpha-background~ and its related
|
||
~alphaBackground~ X resource, it is now possible to set transparency
|
||
only for the frame’s background without affecting any of the other
|
||
elements on screen.
|
||
|
||
**** WebKit inspector in Emacs’ WebKit widget browser
|
||
You can now access the WebKit inspector when using the WebKit widget
|
||
browser in Emacs, given you are using a version of Emacs which has
|
||
been compiled with it. I wish there was a keybinding or at leas a
|
||
function for it, but apparently you can only open it with a right
|
||
click and select /Inspect Element/. Still nice to have.
|
||
|
||
**** Some news for Windows
|
||
Although it has been available for Linux users since Emacs 26.1,
|
||
Windows finally has access to double-buffering to reduce display
|
||
flicker. If you wish to disable it, you can set the frame parameter
|
||
~inhibit-double-buffering~ to ~nil~.
|
||
|
||
Emacs also follows Windows’ dark mode with Windows 10 (version 1809)
|
||
and onwards.
|
||
|
||
Emacs also now uses Windows’ native API to render images. This
|
||
includes BMP, GIF, JPEG, PNG, and TIFF images. Other formats, however,
|
||
still rely on other dependencies and libraries to properly work, such
|
||
as Webp images.
|
||
|
||
*** What’s next?
|
||
With Emacs 29 being cut, development on the master branch will now go
|
||
towards Emacs 30. Is there anything we can expect yet?
|
||
|
||
It’s still very early to say, most stable features merged into master
|
||
went to Emacs 29, and only the ~feature/pkg~ and
|
||
~feature/improved-lock-narrowing~ branches seem to have received commits
|
||
less than a week prior to the day of writing this, and I do not know
|
||
the status of other branches that received commits during the past few
|
||
weeks such as ~feature/package+vc~ or ~feature/eglot2emacs~ (which I
|
||
assume both got merged).
|
||
+However, there are currently talks about including ~use-package~ into Emacs! I’m a bit disappointed it won’t make it into Emacs 29, but progress is being made on ~scratch/use-package~, and you can always check the mailing list to check its status such as [[https://lists.gnu.org/archive/html/emacs-devel/2022-11/msg01533.html][here]].+ *Update*: Rejoice! As mentioned above, ~use-package~ is actually set to land in Emacs 29!
|
||
|
||
** [EN] Automatic Meaningful Custom IDs for Org Headings :emacs:orgmode:dev:
|
||
:PROPERTIES:
|
||
:EXPORT_FILE_NAME: better-custom-ids-orgmode
|
||
:EXPORT_DATE: 2020-06-06
|
||
:export_hugo_menu: :menu "main"
|
||
:END:
|
||
Spoiler alert, I will just modify a bit of code that already exists,
|
||
go directly to the bottom if you want the solution, or read the whole
|
||
post if you are interested in how I got there.
|
||
|
||
#+TOC: headlines 1 local
|
||
|
||
**** Update 2021-11-22
|
||
I’ve put the code presented here as a complete package. You can find
|
||
it in [[https://labs.phundrak.com/phundrak/org-unique-id][this repository]] or in its [[https://github.com/Phundrak/org-unique-id][Github mirror]] (be aware the latter may
|
||
not be as up-to-date as the former is. Installation instructions are
|
||
in the README.
|
||
|
||
*** The issue
|
||
About two to three years ago, as I was working on a project that was
|
||
meant to be published on the internet, I looked for a solution to get
|
||
fixed anchor links to my various headings when I performed HTML
|
||
exports. As some of you may know, by default when an Org file is
|
||
exported to an HTML file, a random ID will be generated for each
|
||
header, and this ID will be used as their anchor. Here’s a quick
|
||
example of a simple org file:
|
||
|
||
#+caption: Example org file
|
||
#+begin_src org :exports code
|
||
,#+title: Sample org file
|
||
,* First heading
|
||
Reference to a subheading
|
||
,* Second heading
|
||
Some stuff written here
|
||
,** First subheading
|
||
Some stuff
|
||
,** Second subheading
|
||
Some other stuff
|
||
#+end_src
|
||
|
||
And this is the result once exported to HTML (with a lot of noise
|
||
removed from ~<head>~):
|
||
|
||
#+caption: Output HTML file
|
||
#+BEGIN_SRC html
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
||
|
||
<head>
|
||
<title>Sample org file</title>
|
||
<meta name="generator" content="Org mode" />
|
||
<meta name="author" content="Lucien Cartier-Tilet" />
|
||
</head>
|
||
|
||
<body>
|
||
<div id="content">
|
||
<h1 class="title">Sample org file</h1>
|
||
<div id="outline-container-orgd8e6238" class="outline-2">
|
||
<h2 id="orgd8e6238"><span class="section-number-2">1</span> First heading</h2>
|
||
<div class="outline-text-2" id="text-1">
|
||
<p>
|
||
Reference to a subheading
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div id="outline-container-org621c39a" class="outline-2">
|
||
<h2 id="org621c39a"><span class="section-number-2">2</span> Second heading</h2>
|
||
<div class="outline-text-2" id="text-2">
|
||
<p>
|
||
Some stuff written here
|
||
</p>
|
||
</div>
|
||
<div id="outline-container-orgae45d6b" class="outline-3">
|
||
<h3 id="orgae45d6b"><span class="section-number-3">2.1</span> First subheading</h3>
|
||
<div class="outline-text-3" id="text-2-1">
|
||
<p>
|
||
Some stuff
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div id="outline-container-org9301aa9" class="outline-3">
|
||
<h3 id="org9301aa9"><span class="section-number-3">2.2</span> Second subheading</h3>
|
||
<div class="outline-text-3" id="text-2-2">
|
||
<p>
|
||
Some other stuff
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
|
||
</html>
|
||
#+END_SRC
|
||
|
||
As you can see, all the anchors are in the fomat of ~org[a-f0-9]{7}~.
|
||
First, this is not really meaningful if you want to read the anchor
|
||
and guess where it will lead you. But secondly, these anchors will
|
||
change each time you export your Org file to HTML. If I want to share
|
||
a URL to my website and to a specific heading,… well I can’t, it will
|
||
change the next time I update the document. And I don’t want to have
|
||
to set a ~CUSTOM_ID~ property for each one of my headings manually. So,
|
||
what to do?
|
||
|
||
*** A first solution
|
||
A first solution I found came from [[https://writequit.org/articles/emacs-org-mode-generate-ids.html][this blog post]], where Lee Hinman
|
||
described the very same issue they had and wrote some Elisp code to
|
||
remedy that (it’s a great read, go take a look). And it worked, and
|
||
for some time I used their code in my Emacs configuration file in
|
||
order to generate unique custom IDs for my Org headers. Basically what
|
||
the code does is it detects if ~auto-id:t~ is set in an ~#+OPTIONS~
|
||
header. If it is, then it will iterate over all of the Org headers,
|
||
and for each one of them it will insert a ~CUSTOM_ID~, which is made
|
||
from a UUID generated by Emacs. And tada! we get for each header a
|
||
~h-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}~ custom
|
||
ID that won’t change next time we export our Org file to HTML when we
|
||
save our file, and only for headings which don’t already have a
|
||
~CUSTOM_ID~ property. Wohoo!
|
||
|
||
Except…
|
||
|
||
*** These headers are not meaningful
|
||
Ok, alright, that’s still a huge step forward, we don’t have to type
|
||
any ~CUSTOM_ID~ property manually anymore, it’s done automatically for
|
||
us. But, when I send someone a link like
|
||
~https://langue.phundrak.com/eittland#h-76fc0b91-e41c-42ad-8652-bba029632333~,
|
||
the first reaction to this URL is often something along the lines of
|
||
“What the fuck?”. And they’re right, this URL is unreadable when it
|
||
comes to the anchor. How am I supposed to guess it links to the
|
||
description of the vowels of the Eittlandic language? (That’s a
|
||
constructed language I’m working on, you won’t find anything about it
|
||
outside my website.)
|
||
|
||
So, I went back to my configuration file for Emacs, and through some
|
||
trial and error, I finally found a way to get a consistent custom ID
|
||
which is readable and automatically set. With the current state of my
|
||
code, what you get is the complete path of the Org heading, all spaces
|
||
replaced by underscores and headings separated by dashes, with a final
|
||
unique identifier taken from an Emacs-generated UUID. Now, the same
|
||
link as above will look like
|
||
~https://langue.phundrak.com/eittland#Aperçu_structurel-Inventaire_phonétique_et_orthographe-Voyelles_pures-84f05c2c~.
|
||
It won’t be more readable to you if you don’t speak French, but you
|
||
can guess it is way better than what we had before. I even added a
|
||
safety net by replacing all forward slashes with dashes. The last ID
|
||
is here to ensure the path will be unique in case we’d have two
|
||
identical paths in the org file for one reason or another.
|
||
|
||
The modifications I made to the first function ~eos/org-id-new~ are
|
||
minimal, where I just split the UUID and get its first part. This is
|
||
basically a way to simplify it.
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun eos/org-id-new (&optional prefix)
|
||
"Create a new globally unique ID.
|
||
|
||
An ID consists of two parts separated by a colon:
|
||
- a prefix
|
||
- a unique part that will be created according to
|
||
`org-id-method'.
|
||
|
||
PREFIX can specify the prefix, the default is given by the
|
||
variable `org-id-prefix'. However, if PREFIX is the symbol
|
||
`none', don't use any prefix even if `org-id-prefix' specifies
|
||
one.
|
||
|
||
So a typical ID could look like \"Org-4nd91V40HI\"."
|
||
(let* ((prefix (if (eq prefix 'none)
|
||
""
|
||
(concat (or prefix org-id-prefix)
|
||
"-"))) unique)
|
||
(if (equal prefix "-")
|
||
(setq prefix ""))
|
||
(cond
|
||
((memq org-id-method
|
||
'(uuidgen uuid))
|
||
(setq unique (org-trim (shell-command-to-string org-id-uuid-program)))
|
||
(unless (org-uuidgen-p unique)
|
||
(setq unique (org-id-uuid))))
|
||
((eq org-id-method 'org)
|
||
(let* ((etime (org-reverse-string (org-id-time-to-b36)))
|
||
(postfix (if org-id-include-domain
|
||
(progn
|
||
(require 'message)
|
||
(concat "@"
|
||
(message-make-fqdn))))))
|
||
(setq unique (concat etime postfix))))
|
||
(t (error "Invalid `org-id-method'")))
|
||
(concat prefix (car (split-string unique "-")))))
|
||
#+END_SRC
|
||
|
||
Next, we have here the actual generation of the custom ID. As you can
|
||
see, the ~let~ has been replaced by a ~let*~ which allowed me to create
|
||
the ID with the variables ~orgpath~ and ~heading~. The former concatenates
|
||
the path to the heading joined by dashes, and ~heading~ concatenates
|
||
~orgpath~ to the name of the current heading joined by a dash if ~orgpath~
|
||
is not empty. It will then create a slug out of the result, deleting
|
||
some elements such as forward slashes or tildes, and all whitespace is
|
||
replaced by underscores. It then passes ~heading~ as an argument to the
|
||
function described above to which the unique ID will be concatenated.
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun eos/org-custom-id-get (&optional pom create prefix)
|
||
"Get the CUSTOM_ID property of the entry at point-or-marker POM.
|
||
|
||
If POM is nil, refer to the entry at point. If the entry does not
|
||
have an CUSTOM_ID, the function returns nil. However, when CREATE
|
||
is non nil, create a CUSTOM_ID if none is present already. PREFIX
|
||
will be passed through to `eos/org-id-new'. In any case, the
|
||
CUSTOM_ID of the entry is returned."
|
||
(interactive)
|
||
(org-with-point-at pom
|
||
(let* ((orgpath (mapconcat #'identity (org-get-outline-path) "-"))
|
||
(heading (replace-regexp-in-string
|
||
"/\\|~\\|\\[\\|\\]" ""
|
||
(replace-regexp-in-string
|
||
"[[:space:]]+" "_" (if (string= orgpath "")
|
||
(org-get-heading t t t t)
|
||
(concat orgpath "-" (org-get-heading t t t t))))))
|
||
(id (org-entry-get nil "CUSTOM_ID")))
|
||
(cond
|
||
((and id
|
||
(stringp id)
|
||
(string-match "\\S-" id)) id)
|
||
(create (setq id (eos/org-id-new (concat prefix heading)))
|
||
(org-entry-put pom "CUSTOM_ID" id)
|
||
(org-id-add-location id
|
||
(buffer-file-name (buffer-base-buffer)))
|
||
id)))))
|
||
#+END_SRC
|
||
|
||
The rest of the code is unchanged, here it is anyway:
|
||
#+BEGIN_SRC emacs-lisp
|
||
(defun eos/org-add-ids-to-headlines-in-file ()
|
||
"Add CUSTOM_ID properties to all headlines in the current file
|
||
which do not already have one.
|
||
|
||
Only adds ids if the `auto-id' option is set to `t' in the file
|
||
somewhere. ie, #+OPTIONS: auto-id:t"
|
||
(interactive)
|
||
(save-excursion
|
||
(widen)
|
||
(goto-char (point-min))
|
||
(when (re-search-forward "^#\\+OPTIONS:.*auto-id:t"
|
||
(point-max)
|
||
t)
|
||
(org-map-entries (lambda ()
|
||
(eos/org-custom-id-get (point)
|
||
'create))))))
|
||
|
||
(add-hook 'org-mode-hook
|
||
(lambda ()
|
||
(add-hook 'before-save-hook
|
||
(lambda ()
|
||
(when (and (eq major-mode 'org-mode)
|
||
(eq buffer-read-only nil))
|
||
(eos/org-add-ids-to-headlines-in-file))))))
|
||
#+END_SRC
|
||
|
||
Note that you *will need* the package ~org-id~ to make this code work. You
|
||
simply need to add the following code before the code I shared above:
|
||
#+BEGIN_SRC emacs-lisp
|
||
(require 'org-id)
|
||
(setq org-id-link-to-org-use-id 'create-if-interactive-and-no-custom-id)
|
||
#+END_SRC
|
||
|
||
And that’s how my links are now way more readable *and* persistent! The
|
||
only downside I found to this is when you move headings and their path
|
||
is modified, or when you modify the heading itself, the custom ID is
|
||
not automatically updated. I could fix that by regenerating the custom
|
||
ID on each save, regardless of whether a custom ID already exists or
|
||
not, but it’s at the risk an ID manually set will get overwritten.
|
||
|
||
#+begin_html
|
||
<script defer src="https://commento.phundrak.com/js/commento.js"></script>
|
||
<div id="commento"></div>
|
||
#+end_html
|
||
|
||
* Linux :@linux:
|
||
** [Fr] Tutoriel Git et Github :linux:git:tutorial:tutoriel:
|
||
:PROPERTIES:
|
||
:EXPORT_FILE_NAME: tutoriel-git-et-github
|
||
:EXPORT_DATE: 2020-06-05
|
||
:export_hugo_menu: :menu "main"
|
||
:END:
|
||
#+TOC: headlines 1 local
|
||
|
||
*** Git ? Qu'est-ce donc ?
|
||
Git est un logiciel de version de fichiers permettant de garder une
|
||
trace de toutes les modifications apportées au fichiers suivis dans un
|
||
répertoire (un dépôt) et ses sous-répertoires –sous couvert qu’ils
|
||
n’aient pas été ignorés explicitement. Il permet également de
|
||
conserver plusieurs versions parallèles du projet, comme par exemple
|
||
une version stable et une version de développement, et permet l’ajout
|
||
de modifications d’une de ces versions parallèles à une autre via des
|
||
fusions partielles ou totales de branches, avec une automatisation des
|
||
fusions de fichiers lorsqu’il n’y a pas de conflit entre ces derniers.
|
||
|
||
Avant de continuer, sache que je suis bilingue français-sarcasme, si
|
||
tu es du genre à t’énerver pour un rien, cette page est à haut risque
|
||
pour toi.
|
||
|
||
Toujours là ? Tu auras été prévenu·e.
|
||
|
||
*** Ça a l’air cool, comment ça s’obtient ?
|
||
**** Et surtout, comment ça s’installe ?
|
||
Très bonne question Kevin. Tout d’abord, il faut t’assurer que git
|
||
soit installé sur ton système et utilisable depuis le terminal. Sous
|
||
GNU/Linux, tu peux l’installer via ton gestionnaire de paquet, ce qui
|
||
rendra la commande accessible directement depuis le terminal. Tu auras
|
||
sans doute besoin de préfixer la commande avec ~sudo~. Si tu n’as pas
|
||
les droits pour utiliser ~sudo~, demande à celui qui a les droits (ton
|
||
administrateur système ou ton papa (j’avais prévenu que je n’allais
|
||
pas être sympa dans ce tutoriel)).
|
||
#+BEGIN_SRC sh
|
||
$ apt install git # Debian, Ubuntu et les distros basées dessus
|
||
$ yum install git # CentOS
|
||
$ dnf -y install git # Fedora
|
||
$ pacman -S git # ArchLinux et les distros basées dessus
|
||
$ emerge --ask --verbose dec-vcs/git # Gentoo
|
||
#+END_SRC
|
||
|
||
#+CAPTION: >install gentoo
|
||
[[./img/install-gentoo.jpg]]
|
||
|
||
Si tu n’es pas sous GNU/Linux mais que tu as au moins le goût d’être
|
||
sous un OS de type Unix, tu peux exécuter la commande correspondante à
|
||
ton OS suivant :
|
||
#+BEGIN_SRC sh
|
||
$ pkg install git # FreeBSD
|
||
$ brew install git # macOS avec brew
|
||
$ port install git +svn +doc +bash_completion +gitweb # macOS avec MacPorts
|
||
#+END_SRC
|
||
|
||
Si tu es sous Windows, soit tu utilises le WSL (Windows Subsystem for
|
||
Linux), soit… bonne chance. Toutes les commandes seront en syntaxe
|
||
Unix dans ce tutoriel, mais si tu as bien deux neurones, tu devrais
|
||
pouvoir tout de même suivre le tutoriel.
|
||
|
||
**** Ok c’est bon, et il y a une configuration à faire ?
|
||
Tu peux configurer Git si tu le souhaites, oui. En général, il est
|
||
recommandé de paramétrer au moins son nom et son e-mail. Tu peux les
|
||
paramétrer via la ligne de commande :
|
||
#+BEGIN_SRC sh
|
||
$ git config --global user.name "Kévin Masturbin"
|
||
$ git config --global user.email "kevin.du.neuftrwa@hotmail.com"
|
||
#+END_SRC
|
||
|
||
Tu peux aussi éditer le fichier =~/.gitconfig= comme suit :
|
||
#+BEGIN_SRC toml
|
||
[user]
|
||
email = ton@email.truc
|
||
name = Ton nom
|
||
#+END_SRC
|
||
|
||
Cela permettra d’associer ton nom et ton adresse mail à tes commits.
|
||
Par défaut, ceux qui sont enregistrés avec ton compte utilisateur de
|
||
ton PC sont mis par défaut dans ces paramètres, mais on met quasiment
|
||
tous un nom à la con quand on le créé. Et ça permet d’avoir les même
|
||
paramètres si tu es sur un autre ordinateur.
|
||
|
||
Il y a encore pas mal de paramètres que tu peux gérer avec ce fichier,
|
||
je reparlerai de certains plus tard, mais pour le reste, la
|
||
documentation en ligne sur ~gitconfig~ ne manque pas.
|
||
|
||
*** Ok très bien, comment on l’utilise maintenant ?
|
||
Du calme Jean-Kevin, ralentis un peu. Comme le dit ce vieux dicton
|
||
Chinois :
|
||
#+begin_quote
|
||
Celui qui marche trop vite…… marche…………… trop… vite…? C’est compliqué les
|
||
dictons chinois…
|
||
#+end_quote
|
||
|
||
De toutes façons, ce dicton est une contrefaçon, donc la qualité de la
|
||
citation n’est pas extraordinaire. Bref.
|
||
|
||
**** Je commence comment ?
|
||
Si tu souhaites créer un dépôt git, rien de plus simple : créé ton
|
||
répertoire dans lequel tu travailleras, et déplace-y-toi. Ensuite, tu
|
||
pourra initialiser ton dépôt via la commande ~git init~.
|
||
#+BEGIN_SRC text
|
||
$ mkdir monsuperprojet
|
||
$ cd monsuperprojet
|
||
$ git init
|
||
Initialized empty Git repository in /tmp/monsuperprojet/.git/
|
||
#+END_SRC
|
||
|
||
Si tu obtiens à peu près le même message après la dernière commande,
|
||
félicitations ! Tu viens de créer ton premier dépôt git. En
|
||
l’occurrence, j’ai créé mon dépôt dans ~/tmp~, mais toi tu peux voir un
|
||
truc du genre ~/home/corentin/monsuperprojet~ à la place. Tu peux
|
||
vérifier que tout va bien en rentrant la commande ~git status~.
|
||
#+BEGIN_SRC text
|
||
$ git status
|
||
On branch master
|
||
|
||
No commits yet
|
||
|
||
nothing to commit (create/copy files and use "git add" to track)
|
||
#+END_SRC
|
||
|
||
Parfait ! Ah, et ne met rien d’important dans ~/tmp~, ce dossier est
|
||
réinitialisé à chaque redémarrage de ta machine. Ou alors, met-y
|
||
uniquement des fichiers que tu ne souhaites avoir que temporairement
|
||
sur ta machine (comme ce meme que tu télécharges depuis Reddit pour le
|
||
reposter sur Discord).
|
||
|
||
**** Et pour rajouter des fichiers ?
|
||
Maintenant tu peux commencer à travailler sur ton projet. Mais tout
|
||
d’abord, on va voir ce qu’il se passe si jamais on créé un fichier
|
||
dans le dépôt. Créé un fichier ~main.c~ dans lequel tu vas entrer ce
|
||
code :
|
||
#+BEGIN_SRC c
|
||
#include <stdio.h>
|
||
|
||
int main(int ac, char* av[]) {
|
||
printf("Hello World!\n");
|
||
return 0;
|
||
}
|
||
#+END_SRC
|
||
|
||
Bref, si tu exécutes à nouveau git status, tu obtients cette sortie :
|
||
#+BEGIN_SRC text
|
||
$ git status
|
||
On branch master
|
||
|
||
No commits yet
|
||
|
||
Untracked files:
|
||
(use "git add <file>..." to include in what will be committed)
|
||
|
||
main.c
|
||
|
||
nothing added to commit but untracked files present (use "git add" to track)
|
||
#+END_SRC
|
||
|
||
Tu commences à comprendre un peu le bail ? Git vient de détecter qu’un
|
||
nouveau fichier a été créé qu’il ne connaissait pas avant. Suivons ses
|
||
bon conseils et ajoutons le fichier au dépôt.
|
||
#+BEGIN_SRC text
|
||
$ git add main.c
|
||
$ git status
|
||
On branch master
|
||
|
||
No commits yet
|
||
|
||
Changes to be committed:
|
||
(use "git rm --cached <file>..." to unstage)
|
||
|
||
new file: main.c
|
||
#+END_SRC
|
||
|
||
Super, maintenant git va surveiller les changements du fichier, mais
|
||
attention, il n’a pas encore enregistré son état. Pour l’instant il
|
||
sait juste que le fichier est là, dans un certain état, mais rien ne
|
||
garanti encore qu’on pourra retrouver cet état plus tard. On appelle
|
||
ça le /staging/. Pour ce faire, il faut créer ce qu’on appelle un
|
||
/commit/. En gros, il s’agit d’un enregistrement des modifications
|
||
apportées à un ou plusieurs fichiers (dans leur globalité ou
|
||
partiellement, on verra ça plus tard), le tout avec un commentaire.
|
||
#+BEGIN_SRC text
|
||
$ git commit -m "Un petit pas pour moi, un grand pas pour mon projet"
|
||
[master (root-commit) 89139ef] Un petit pas pour moi, un grand pas pour mon projet
|
||
1 file changed, 6 insertions(+)
|
||
create mode 100644 main.c
|
||
#+END_SRC
|
||
|
||
Parfait ! Certains éléments peuvent être un peu différent chez toi,
|
||
comme par exemple la référence du commit juste avant le message. Ça,
|
||
c’est un truc qui est géré automatiquement par git. Et voilà, on a
|
||
l’état de notre répertoire qui est enregistré et qui sera disponible
|
||
plus tard. Maintenant, tu sais comment enregistrer des état de ton
|
||
dépôt via les commits.
|
||
|
||
**** Cool, mais j’ai accidentellement mis un fichier en staging
|
||
Si jamais tu as un staging que tu veux annuler, tu peux utiliser la
|
||
commande ~git reset HEAD nomdufichier~ (ou plusieurs noms de fichiers)
|
||
pour annuler le staging. Une fois le fichier qui n’est plus dans ton
|
||
staging, tu peux même annuler toutes les modifications que tu as
|
||
apporté au fichier depuis ton dernier commit avec la commande ~git
|
||
checkout -- nomdufichier~, et tu peux aussi mettre plusieurs noms de
|
||
fichiers. Par exemple, si j’ai modifié mon ~main.c~ en modifiant ainsi
|
||
les arguments du ~main()~ :
|
||
#+BEGIN_SRC c
|
||
#include <stdio.h>
|
||
|
||
int main(void) {
|
||
printf("Hello World!\n");
|
||
return 0;
|
||
}
|
||
#+END_SRC
|
||
|
||
Je peux annuler tout ça via ces commandes :
|
||
#+BEGIN_SRC text
|
||
$ git reset HEAD main.c
|
||
Unstaged changes after reset:
|
||
M main.c
|
||
$ git checkout -- main.c
|
||
$ git status
|
||
On branch master
|
||
nothing to commit, working tree clean
|
||
#+END_SRC
|
||
|
||
Si je fait un ~cat main.c~, je vois qu’il est revenu à son état initial.
|
||
|
||
Et petite remarque concernant les arguments de la fonction ~main~ en C :
|
||
on peut leur donner le nom que l’on souhaite (personellement j’aime
|
||
bien parfois metre ~ac~ et ~av~ au lieu de ~argc~ et ~argv~), ça ne changera
|
||
strictement rien au comportement du code. Et si l’on ne souhaite pas
|
||
utiliser les arguments reçus par le ~main~, on peut simplement déclarer
|
||
la fonction main comme ~main(void)~. Au moins, c’est clair pour le
|
||
compilateur et le lecteur du code : on s’en fiche des arguments du
|
||
~main~.
|
||
|
||
Par contre, chose importante : mettre void en arguments du main est du
|
||
C, *et ce n’est pas valide en C++*. /Le C++ n’est pas du C avec des
|
||
fonctionnalités en plus/.
|
||
|
||
**** En fait, j’ai juste oublié un truc dans mon commit précédent
|
||
Si jamais tu veux à la place ajouter la modification d’un fichier au
|
||
dernier commit (mettons, tu as oublié d’ajouter également un fichier
|
||
texte), tu peux utiliser l’option ~--amend~ lors du commit du fichier
|
||
oublié.
|
||
#+BEGIN_SRC text
|
||
$ git add main.c # J’ai refait les modifications annulées plus tôt
|
||
$ git commit -m "second commit"
|
||
[master 97f698a] second commit
|
||
1 file changed, 1 insertion(+), 1 deletion(-)
|
||
$ echo "C’est un super projet !" > projet.txt
|
||
$ git add projet.txt
|
||
$ git commit --amend -m "second commit + oubli"
|
||
[master 9aff4c0] second commit + oubli
|
||
Date: Fri Oct 5 11:10:56 2018 +0200
|
||
2 files changed, 2 insertions(+), 1 deletion(-)
|
||
create mode 100644 projet.txt
|
||
#+END_SRC
|
||
|
||
En gros, le commit que tu viens de faire a remplacé le précédent en
|
||
conservant les informations du commit précédent, mis à part son
|
||
commentaire. Si tu ne met pas l’option ~-m "ton texte"~ lors de
|
||
l’amendement du commit, ton éditeur texte par défaut va s’ouvrir pour
|
||
que tu puisses modifier le texte du commit précédent si tu le
|
||
souhaite. Si jamais vim s’ouvre et que tu n’as aucune idée de comment
|
||
sortir de cet enfant du démon, tu as juste à appuyer sur la touche
|
||
Échap (au cas où), puis à taper ~:wq~ (~w~ pour écrire le fichier, ~q~ pour
|
||
quitter), puis tu appuie sur la touche Entrée. Si tu as Nano qui s’est
|
||
ouvert, alors il faut taper Ctrl-X. Dans tous les cas, tu aurais dû
|
||
utiliser Emacs.
|
||
|
||
**** Euh, j’ai oublié ce que j’ai changé lors du dernier commit
|
||
Pas de panique ! Tu peux entrer la commande ~git diff~ afin de voir ce
|
||
que tout ce que tu as modifié lors de ton dernier commit. Et si tu ne
|
||
souhaite voir les modifications que d’un certain fichier, tu peux
|
||
ajouter le nom de ton fichier à la fin de la commande.
|
||
#+BEGIN_SRC text
|
||
$ echo "C’est un super projet !" > projet.txt
|
||
$ git diff
|
||
diff --git a/projet.txt b/projet.txt
|
||
index 03b0f20..b93413f 100644
|
||
--- a/projet.txt
|
||
+++ b/projet.txt
|
||
@@ -1 +1 @@
|
||
-projet
|
||
+C’est un super projet !
|
||
#+END_SRC
|
||
|
||
Tu peux également voir les différences de fichiers entre deux commits
|
||
en entrant leur référence. Pour avoir la référence, tu peux rentrer la
|
||
commande ~git log~ pour avoir un petit historique des commits.
|
||
#+BEGIN_SRC text
|
||
$ git log
|
||
commit 4380d8717261644b81a1858920406645cf409028 (HEAD -> master)
|
||
Author: Phuntsok Drak-pa <phundrak@phundrak.fr>
|
||
Date: Fri Oct 5 11:59:40 2018 +0200
|
||
|
||
new commit
|
||
|
||
commit 59c21c6aa7e3ec7edd229f81b87becbc7ec13596
|
||
Author: Phuntsok Drak-pa <phundrak@phundrak.fr>
|
||
Date: Fri Oct 5 11:10:56 2018 +0200
|
||
|
||
nouveau texte
|
||
|
||
commit 89139ef233d07a64d3025de47f8b6e8ce7470318
|
||
Author: Phuntsok Drak-pa <phundrak@phundrak.fr>
|
||
Date: Fri Oct 5 10:56:58 2018 +0200
|
||
|
||
Un petit pas pour moi, un grand pas pour mon projet
|
||
#+END_SRC
|
||
|
||
Bon, c’est un peu long et un peu trop d’infos d’un coup, généralement
|
||
je préfère taper ~git log --oneline --graph --decorate~ afin d’avoir un
|
||
affichage comme suit :
|
||
#+BEGIN_SRC text
|
||
$ git log --oneline --graph --decorate
|
||
,* 4380d87 (HEAD -> master) new commit
|
||
,* 59c21c6 nouveau texte
|
||
,* 89139ef Un petit pas pour moi, un grand pas pour mon projet
|
||
#+END_SRC
|
||
|
||
Plus propre, non ? Et les références sont plus courtes, ce qui est
|
||
plus agréable à taper. Allez, comparons les deux derniers commits.
|
||
#+BEGIN_SRC text
|
||
$ git add .
|
||
$ git commit -m "new commit"
|
||
$ git log --oneline --graph --decorate
|
||
,* 4380d87 (HEAD -> master) new commit
|
||
,* 59c21c6 nouveau texte
|
||
,* 89139ef Un petit pas pour moi, un grand pas pour mon projet
|
||
$ git diff 59c21c6 4380d87
|
||
diff --git a/projet.txt b/projet.txt
|
||
index 03b0f20..b93413f 100644
|
||
--- a/projet.txt
|
||
+++ b/projet.txt
|
||
@@ -1 +1 @@
|
||
-projet
|
||
+C’est un super projet !
|
||
#+END_SRC
|
||
|
||
**** Il y a des fichiers dont je me fiche dans mon dépôt
|
||
Dans ce cas, il est grand temps de te présenter le fichier ~.gitignore~.
|
||
Comme son nom l’indique, il permet au dépôt d’ignorer des fichiers
|
||
selon ce que tu lui indiqueras. Par exemple, si tu veux ignorer tous
|
||
les fichiers qui se terminent en ~.out~ (ou ~.exe~ sous Windows), tu peux
|
||
éditer (ou créer) ton ~.gitignore~ et entrer ces lignes :
|
||
#+BEGIN_SRC gitignore
|
||
,*.out
|
||
,*.exe
|
||
#+END_SRC
|
||
|
||
Maintenant, si tu créés un fichier en ~.out~ ou ~.exe~, il sera
|
||
complètement ignoré par git et ne sera pas stocké dans l’historique
|
||
des versions. Il s’agit de ce qu’on appelle du globbing. En gros,
|
||
l’étoile indique que tu t’en fiches de ce qu’il y a devant ~.out~ ou
|
||
~.exe~ dans cet exemple, si quelque chose se termine par ça, c’est
|
||
ignoré. Pour ignorer quelque chose dans un dossier, tu pourrais avoir
|
||
quelque chose du genre ~mondossier/*~ et POUF, tous les fichiers de
|
||
~mondossier/~ sont ignorés. En gros, le globbing va fonctionner comme le
|
||
globbing de ton shell (Bash, Zsh, Fish,…)
|
||
|
||
Par exemple, [[https://labs.phundrak.com/phundrak/langue-phundrak-com/commit/f8ec1936f839e9e95a6badf4480589f5bc9d00a0][voici un dépôt]] un peu plus complexe que ce qu’on est en
|
||
train de faire (figé lors d’un commit fixé). Tu peux voir dans mon
|
||
~.gitignore~ qu’il y a pas mal d’extensions de fichiers qui sont
|
||
ignorées, mais j’ai aussi ~_minted*~ et ~auto-generated*~ qui sont des
|
||
dossiers ignorés, et pas juste leur contenu qui est ignoré (l’étoile
|
||
est là pour ignorer tous les dossiers dont le nom commence par ce qui
|
||
précède l’étoile). J’ai aussi ignoré le dossier ~.dart_tool/~ qui lui
|
||
pour le coup n’a pas de globbing, ainsi que le fichier ~pubspec.lock~,
|
||
sans globbing non plus.
|
||
|
||
**** On est plusieurs dessus en fait…
|
||
Pas de panique ! Git a été créé pour ça, et il dispose d’une
|
||
fonctionnalité de branchage permettant d’avoir plusieurs versions
|
||
coexistantes d’un même fichier. Cela peut être très utile pour avoir
|
||
soit plusieurs personnes travaillant sur un même projet, soit pour une
|
||
même personne travaillant sur plusieurs fonctionnalités différentes,
|
||
soit les deux. Ainsi, on a plusieurs version indépendantes que l’on
|
||
pourra fusionner plus tard.
|
||
|
||
Par défaut une branche est créée lors de la création d’un dépôt qui
|
||
s’appelle ~master~. Pour créer une nouvelle branche, on peut donc
|
||
utiliser la commande ~git checkout -b nomdelanouvellebranche~.
|
||
#+BEGIN_SRC text
|
||
$ git checkout -b nouvelle-branche
|
||
Switched to a new branch 'nouvelle-branche'
|
||
#+END_SRC
|
||
|
||
À partir d’ici, toute modification apportée aux fichiers du dépôt
|
||
n’affecteront que la branche courante, ~nouvelle-branche~ donc, et les
|
||
fichiers de la branche ~master~ resteront inchangés. Si jamais tu veux
|
||
retourner pour une quelconque raison sur la branche ~master~, il te
|
||
suffira d’utiliser la commande ~git checkout master~.
|
||
|
||
Si tu souhaites avoir une liste des branches du dépôt, tu peux taper
|
||
~git branch --list~. La branche active sera marquée d’une étoile à côté
|
||
de son nom.
|
||
#+BEGIN_SRC text
|
||
$ git branch --list
|
||
master
|
||
,* nouvelle-branche
|
||
#+END_SRC
|
||
|
||
**** J’ai accidentellement modifié des fichiers sur la mauvaise branche, mais je n’ai pas encore fait de commits.
|
||
Tout va bien alors ! Tu vas simplement exécuter cette commande :
|
||
#+BEGIN_SRC text
|
||
$ git stash
|
||
#+END_SRC
|
||
|
||
Ça va déplacer toutes tes modifications que tu n’as pas encore commit
|
||
dans le stash, qui est une sorte d’emplacement temporaire, en dehors
|
||
des branches. Normalement, ça va réinitialiser tes fichiers tels
|
||
qu’ils étaient lors du dernier commit. Maintenant, change la branche
|
||
sur laquelle tu travailles, par exemple tu si tu es sur la branche
|
||
~kevin~, tu exécutes ceci :
|
||
#+BEGIN_SRC text
|
||
$ git checkout kevin
|
||
#+END_SRC
|
||
|
||
Tes modifications sont toujours dans ton stack, et pour les restaurer,
|
||
tu n’as plus qu’à exécuter
|
||
#+BEGIN_SRC text
|
||
$ git stash pop
|
||
#+END_SRC
|
||
|
||
Et voilà, tu viens de déplacer tes modifications sur la bonne branche.
|
||
Pour information, si tu as créé un nouveau fichier ou un nouveau
|
||
dossier avec des fichiers, ils ne seront pas déplacés dans le stash,
|
||
mais ils ne seront pas supprimés lors de la première commande. Tu
|
||
auras juste à les commit sur ta nouvelle branche pour qu’ils cessent
|
||
de se déplacer de branche en branche.
|
||
|
||
**** Du coup, Mathilde a bien avancé sur son code, et moi aussi, chacun sur notre branche. On fait comment maintenant ?
|
||
Au bout d’un moment, tu vas sans doute vouloir fusionner deux
|
||
branches, par exemple tu as finis de développer une nouvelle
|
||
fonctionnalité sur la branche ~nouvelle-branche~ et tu souhaites
|
||
l’ajouter à la version stable de ton code qui se situe sur ~master~.
|
||
Dans ce cas, ce que tu peux faire, c’est retourner sur ta branche
|
||
~master~, puis tu vas effectuer ce qu’on appelle un merge ; en gros,
|
||
pour faire simple, tu vas appliquer les modifications de la branche
|
||
que tu souhaites fusionner avec ta branche ~master~ sur cette dernière.
|
||
#+BEGIN_SRC text
|
||
$ git checkout master
|
||
Switched to branch 'master'
|
||
$ git merge nouvelle-branche
|
||
Updating 133c5b6..2668937
|
||
Fast-forward
|
||
projet.txt | 1 +
|
||
1 file changed, 1 insertion(+)
|
||
create mode 100644 projet.txt
|
||
#+END_SRC
|
||
|
||
Rappelle-toi que la commande ~merge~ ramène les commits de la branche
|
||
spécifiée vers ta branche active, et pas forcément vers le ~master~. Du
|
||
coup, si tu est sur une branche ~mathilde~ et que tu effectues un ~git
|
||
merge leon~, tu vas ramener tous les commits de leon vers la branche
|
||
mathilde. Ça peut être intéressant à faire si jamais un bug a été
|
||
corrigé dans une autre branche ou qu’une fonctionnalité a été ajoutée
|
||
et que tu veux en bénéficier dans ta branche active. N’oublie juste
|
||
pas de tout bien commit avant de faire ton merge.
|
||
|
||
*** J’ai entendu parler de Github…
|
||
Tu commences à me plaire Enzo ! Github est un site web sur lequel tu
|
||
peux héberger des projets libres ou open-source (si tu ne connais pas
|
||
la différence, voici un article pour t’aider à comprendre, et un autre
|
||
pour la route). C’est en particulier orienté pour les projets gérés
|
||
par git, ce qui tombe bien car c’est ce qu’on utilise. Cela a pour
|
||
avantage de pouvoir aisément partager ton code et d’assurer qu’il est
|
||
bien sauvegardé quelque part d’autre que ton disque dur (un ~rm -rf~ est
|
||
si vite arrivé). Et surtout, ça peut te permettre de collaborer avec
|
||
d’autres personnes sur le même projet sans te casser la tête.
|
||
|
||
#+begin_quote
|
||
Git est à Github ce que le porn est à Pornhub.
|
||
#+end_quote
|
||
|
||
J’aimerais tout de même te mettre au courant que Github n’est
|
||
largement pas le seul site de ce genre à exister. Le concurrent le
|
||
plus célèbre de Github est [[https://about.gitlab.com/][Gitlab]], et personnellement j’utilise [[https://gitea.io/en-us/][Gitea]].
|
||
Ces deux derniers peuvent même être hébergés en instances
|
||
personnelles, comme [[https://labs.phundrak.com/phundrak/langue-phundrak-com/commit/f8ec1936f839e9e95a6badf4480589f5bc9d00a0][ce que je fais avec Gitea]] (qui est beaucoup plus
|
||
léger que Gitlab, mais avec quelques fonctionnalités en moins), et il
|
||
existe encore [[https://labs.phundrak.com/phundrak/langue-phundrak-com/commit/f8ec1936f839e9e95a6badf4480589f5bc9d00a0][plein d’autres alternatives]], à toi de trouver les
|
||
autres.
|
||
|
||
*** J’ai téléchargé un projet en zip
|
||
Ou bien, tu peux télécharger le projet directement via git. Eh oui !
|
||
git permet de gérer les dépôts dits distants, c’est à dire ceux qui
|
||
sont hébergés sur un serveur en ligne, comme par exemple sur Github.
|
||
Pour cela, il te faut te munir du lien vers le dépôt git, et le passer
|
||
en argument de git clone. Par exemple, si tu veux télécharger de dépôt
|
||
du petit logiciel de chat en réseau que j’ai codé durant ma L2
|
||
d’informatique, tu peux exécuter ceci :
|
||
#+BEGIN_SRC text
|
||
$ git clone https://github.com/noalien/GL4Dummies.git
|
||
Cloning into 'GL4Dummies'...
|
||
remote: Enumerating objects: 682, done.
|
||
remote: Counting objects: 100% (682/682), done.
|
||
remote: Compressing objects: 100% (455/455), done.
|
||
remote: Total 3516 (delta 354), reused 509 (delta 215), pack-reused 2834
|
||
Receiving objects: 100% (3516/3516), 72.95 MiB | 2.13 MiB/s, done.
|
||
Resolving deltas: 100% (2019/2019), done.
|
||
#+END_SRC
|
||
|
||
Et c’est bon, tu as accès au répertoire ~GL4Dummies~ et au code source
|
||
du projet. (Courage aux élèves de Paris 8 qui feront de la
|
||
programmation graphique !)
|
||
|
||
*** Et si je veux créer mon propre dépôt sur Github
|
||
Dans ce cas là, c’est simple Brigitte. Il faut que tu te créés un
|
||
compte sur Github, puis tu cliques sur le bouton ~+~ et ~New Repository~.
|
||
Tu lui donnes le nom que tu souhaites (en l’occurrence je le nomme
|
||
~temporary-repo~ car je vais le supprimer cinq minutes après l’écriture
|
||
de ces lignes), et tu cliques sur ~Create Repository~. Tu n’ajoutes rien
|
||
avant, pas de description, pas de ~.gitignore~, RIEN.
|
||
|
||
Et là, magie ! Github indique comment ajouter le dépôt distant à ton
|
||
dépôt local.
|
||
#+BEGIN_SRC text
|
||
$ git remote add origin https://github.com/Phundrak/temporary-repo.git
|
||
#+END_SRC
|
||
|
||
Et voilà, ton dépôt est lié au dépôt distant. Oui, juste comme ça.
|
||
|
||
Sinon, si tu souhaites d’abord créer ton dépôt sur Github puis sur ta
|
||
machine, tu peux aussi très bien le créer sur Github (logique) puis le
|
||
cloner sur ta machine comme je te l’ai montré avant.
|
||
|
||
*** Et du coup, comment je met tout ça en ligne ?
|
||
Bon ok, ce n’est pas aussi simple que ça. Une fois que tu as lié ton
|
||
dépôt au dépôt distant, il faudra que tu mettes en ligne tes commits
|
||
quand tu en auras l’occasion. Pour ce faire, tu n’as qu’à taper ~git
|
||
push~ ; et la première fois, il faudra que tu indiques à ton dépôt où
|
||
mettre en ligne précisément dans le dépôt distant, auquel cas tu
|
||
ajoutes ~-u origin master~ pour cette première fois. Git te demandera
|
||
donc tes identifiants Github pour pouvoir mettre tout ça en ligne.
|
||
#+BEGIN_SRC text
|
||
$ git push -u origin master
|
||
Username for 'https://github.com': phundrak
|
||
Password for 'https://phundrak@github.com':
|
||
Enumerating objects: 10, done.
|
||
Counting objects: 100% (10/10), done.
|
||
Delta compression using up to 8 threads
|
||
Compressing objects: 100% (7/7), done.
|
||
Writing objects: 100% (10/10), 940 bytes | 313.00 KiB/s, done.
|
||
Total 10 (delta 0), reused 0 (delta 0)
|
||
remote:
|
||
remote: Create a pull request for 'master' on GitHub by visiting:
|
||
remote: https://github.com/Phundrak/temporary-repo/pull/new/master
|
||
remote:
|
||
To https://github.com/Phundrak/temporary-repo.git
|
||
,* [new branch] master -> master
|
||
Branch 'master' set up to track remote branch 'master' from 'origin'.
|
||
#+END_SRC
|
||
|
||
Bon, là en nom d’utilisateur il y a le mien, faudra remplacer avec le
|
||
tiens. Et ouais, ma vitesse de mise en ligne n’est pas fameuse, je
|
||
suis sur une connexion 3G+ à l’heure où j’écris ces lignes, ne me juge
|
||
pas. Bref, toujours est-il que je viens de mettre en ligne les
|
||
fichiers du dépôt sur Github. Pas la peine de chercher le mien sur
|
||
Github par contre, ça fera un bail que je l’aurai supprimé au moment
|
||
où tu liras ces lignes.
|
||
|
||
Pour info, tu peux éviter d’avoir à taper ton identifiant et ton mot
|
||
de passe à chaque fois que tu fais un push sur ton dépôt si tu
|
||
indiques à Github ta clef SSH. Tu auras plus d’informations là (c’est
|
||
à peu près la même merde pour Gitlab, Gitea et Cie).
|
||
|
||
*** Quelqu’un a fait des modifications depuis mon dernier commit, je récupère ça comment ?
|
||
Pour faire un exemple, je viens de créer un ~README.md~ sur Github
|
||
directement. Ce type de fichiers est assez standard afin de présenter
|
||
plus ou moins en détails le dépôt et le projet qui y est lié, et son
|
||
contenu apparaîtra formaté sur la page du dépôt sur Github s’il est au
|
||
format ~.md~ (Markdown) ou ~.org~ (org-mode, le Markdown d’Emacs avec
|
||
lequel est écrit ce tutoriel, et qui est clairement supérieur à
|
||
Markdown). Mais il n’est pas présent dans mon dépôt local, du coup je
|
||
vais devoir le récupérer. On va donc entrer git pull.
|
||
#+BEGIN_SRC text
|
||
$ git pull
|
||
remote: Enumerating objects: 4, done.
|
||
remote: Counting objects: 100% (4/4), done.
|
||
remote: Compressing objects: 100% (3/3), done.
|
||
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
|
||
Unpacking objects: 100% (3/3), done.
|
||
From https://github.com/Phundrak/temporary-repo
|
||
4380d87..8bd4896 master -> origin/master
|
||
Updating 4380d87..8bd4896
|
||
Fast-forward
|
||
README.md | 2 ++
|
||
1 file changed, 2 insertions(+)
|
||
create mode 100644 README.md
|
||
#+END_SRC
|
||
|
||
*** Je suis en train de travailler sur le même fichier que Ginette
|
||
Là, c’est un problème qui aurait pu être évité avec l’usage des
|
||
branches dont je t’avais parlé plus haut, mais visiblement, vous êtes
|
||
sur la même branche. Pas bien. Dans ce cas-là, met-toi d’accord avec
|
||
Ginette pour savoir qui fait ses push en premier. Si le choix tombe
|
||
sur Ginette, ou si elle a imposé sa vision des choses et a fait son
|
||
push avant toi, Github va râler car tu n’es pas à jour. Dans ce cas ne
|
||
panique pas, si tu n’as pas fait tes commits, lance la commande ~git
|
||
stash~ ; ça va sauvegarder tes modifications dans un coin à part et va
|
||
annuler tes modifications.
|
||
|
||
*** Github ne veut pas de mes pushs sur le dépôt de Gilberte, oskour !
|
||
Du calme Jean-Célestin. Cela veut tout simplement dire que tu n’as
|
||
tout simplement pas les droits d’écriture sur son dépôt. Du coup, soit
|
||
tu peux lui demander directement à ce qu’elle te donne les droits
|
||
d’écriture si elle a confiance en toi, soit tu peux créer un fork puis
|
||
une pull-request sur Github depuis ton fork où tu auras fait tes
|
||
modifications.
|
||
|
||
*** Fork ? Pull request ? Que font des fourchettes et des pulls dans ce tuto ?
|
||
Ouhlà Billy, il va falloir remettre les choses au clair. Là il s’agit
|
||
de quelque chose de spécifique à Github qu’à Git (d’où le fait qu’on
|
||
en discute dans ce chapitre que le précédent).
|
||
|
||
Sur Github, il est possible de copier vers ton profil le dépôt de
|
||
quelqu’un d’autre dans l’état où il est au moment du fork. Cela inclus
|
||
les fichiers du ~master~, mais également de toutes les branches du
|
||
dépôt. Tu peux y penser en terme de super-branche dont tu deviens le
|
||
propriétaire. Tu peux ainsi travailler comme bon te semble sur le code
|
||
source sans que son propriétaire ne vienne t’engueuler car tu es en
|
||
train de polluer sa base de code.
|
||
|
||
Si jamais il y a une modification dont tu es particulièrement fier, tu
|
||
peux la soumettre au propriétaire du dépôt original (et à ses
|
||
modérateurs et contributeurs s’il y en a) via ce qu’on appelle une
|
||
pull-request. Cela signifie donc que tu demandes l’autorisation
|
||
d’ajouter des commits à la base de code, et ces commits peuvent être
|
||
lus et commentés par le propriétaire ou les modérateurs. Il peut y
|
||
avoir une discussion entre toi et les autres personnes qui ont leur
|
||
mot à dire, le code peut être temporairement refusé, auquel cas tu
|
||
peux reproposer de nouveau commits sur la même pull-request jusqu’à ce
|
||
que ton code soit définitivement accepté ou refusé. Dans tous les cas,
|
||
cela mènera à la fermeture de ta pull-request, et tu pourras fièrement
|
||
annoncer que tu as participé à un projet sur Github, ou bien avouer
|
||
avec toute la honte du monde qu’il a été refusé.
|
||
|
||
*** J’ai remarqué un bug ou une erreur, mais je ne peux pas corriger ça moi-même
|
||
Eh bien dans ce cas-là, ouvre une /issue/ Bernadette ; /issue/ qui en
|
||
français veut dire /problème/. Il s’agit d’un système de Github te
|
||
permettant de signaler quelque chose aux propriétaires du dépôt, il
|
||
peut s’agir d’un bug, d’une demande de fonctionnalité ou de
|
||
proposition de modification d’autres fonctionnalités. Cela peut donner
|
||
lieu à des discussions menant à la compréhension du bug, ou à une
|
||
amélioration de ta proposition.
|
||
|
||
Si tu soumets un bug, avant d’ouvrir une nouvelle issue, assure-toi de
|
||
bien savoir comment le bug se produit et peut se reproduire. Est-ce
|
||
que le bug apparaît si tu utilise ou ouvre le logiciel d’une autre
|
||
façon ? Est-ce que le bug apparaît ailleurs ? Est-tu sûr que le bug
|
||
soit un bug ? Et si tu décides de le partager, assure-toi de partager
|
||
un maximum d’information et tout ce que tu sais sur ce bug, en
|
||
particulier les étapes et conditions pour le reproduire.
|
||
|
||
*** Les raccourcis et paramètres de Git
|
||
Comme j’en avais parlé plus haut, il est possible de configurer git de
|
||
façon un peu plus poussée que simplement déclarer notre nom et notre
|
||
adresse e-mail dans notre =~/.gitconfig=. Il est par exemple possible de
|
||
déclarer notre éditeur texte préféré, notre navigateur par défaut ou
|
||
bien même des raccourcis qui pourront t’être bien utile. Ci dessous je
|
||
te met une partie de mon fichier de configuration avec quelques-unes
|
||
de mes préférences et pas mal de mes alias.
|
||
#+BEGIN_SRC toml
|
||
[core]
|
||
editor = emacsclient -c
|
||
whitespace = fix,-indent-with-non-tab,trailing-space
|
||
[web]
|
||
browser = firefox
|
||
[color]
|
||
ui = auto
|
||
[alias]
|
||
a = add --all
|
||
c = commit
|
||
cm = commit -m
|
||
cam = commit -am
|
||
co = checkout
|
||
cob = checkout -b
|
||
cl = clone
|
||
l = log --oneline --graph --decorate
|
||
ps = push
|
||
pl = pull
|
||
re = reset
|
||
s = status
|
||
staged = diff --cached
|
||
st = stash
|
||
sc = stash clear
|
||
sp = stash pop
|
||
sw = stash show
|
||
#+END_SRC
|
||
|
||
- ~a~ :: Permet d’ajouter d’un coup tout nouveau fichier d’un dépôt en
|
||
préparation au commit. On peut faire la même chose avec ~git add .~ si
|
||
on est à la racine du dépôt.
|
||
- ~c~ :: Un raccourci pour commit, ça permet d’éviter quelques frappes
|
||
de clavier d’écrire ~git c~ plutôt que ~git commit~.
|
||
- ~cm~ :: De même pour ~cm~ qui évite de devoir écrire ~commit -m~. On n’a
|
||
plus qu’à écrire directement le message de commit après ~cm~.
|
||
- ~cam~ :: Non, ce n’est pas un plan, c’est le même alias que ~cm~ mais
|
||
qui en plus met automatiquement tous les fichiers modifiés ou
|
||
supprimés, donc s’il n’y a pas de nouveau fichier à ajouter, même
|
||
pas besoin de passer par un ~git a~ avant le ~git cam "j’aime les
|
||
pâtes"~.
|
||
- ~co~ :: Pour aller plus vite quand on veut écrire ~checkout~.
|
||
- ~cob~ :: Et pour en plus rajouter le flag ~-b~ pour la création d’une
|
||
nouvelle branche.
|
||
- ~cl~ :: Pour quand tu voudras télécharger ce tutoriel en tapant ~git cl
|
||
https://github.com/Phundrak/tutoriel-git.git~ plutôt que ~git clone
|
||
https://github.com/Phundrak/tutoriel-git.git~.
|
||
- ~l~ :: Te permet d’avoir le log un peu plus sympa et compact dont
|
||
j’avais parlé plus haut.
|
||
- ~ps~ :: Pour faire un push plus rapidement.
|
||
- ~pl~ :: Et pour télécharger les derniers commits sur le dépôt plus
|
||
rapidement.
|
||
- ~re~ :: Pour réinitialiser plus rapidement.
|
||
- ~s~ :: Pour rapidement savoir où tu en es dans ton dépôt, savoir ce
|
||
qui a été modifié, ajouté, supprimé, déplacé, tout ça…
|
||
- ~staged~ :: Eh oui, Git n’a pas de fonction dédiée pour lister les
|
||
fichiers en staging, du coup la voilà.
|
||
- ~st~ :: Pour sauvegarder tes modifications sur le stash plus
|
||
rapidement.
|
||
- ~sc~ :: Pour supprimer ton stash plus rapidement.
|
||
- ~sp~ :: Pour rétablir le stash sur la branche courante plus
|
||
rapidement.
|
||
- ~sw~ :: Pour rapidement savoir ce qu’il y a sur le stash.
|
||
|
||
*** Et c’est tout ?
|
||
C’est déjà pas mal ! Mais non, ce n’est certainement pas tout.
|
||
Cependant, ce tutoriel n’a pour but de t’apprendre que les bases de
|
||
Git et de Github, pas de tout t’apprendre ! Si tu souhaites aller plus
|
||
loin, connaître plus de commandes (comme ~git blame~ ou ~git reset~), ou
|
||
bien connaître plus d’options, je ne peux que t’inviter à aller te
|
||
documenter par toi-même sur le site de Git qui se trouve ici, ou bien
|
||
à consulter des pages de manuel dans ton terminal via ~man git~, ~man
|
||
git-apply~ ou ~man git-cherry-pick~ (oui, il faut lier ~git~ et le nom de
|
||
la commande par un tiret d’union).
|
||
|
||
Si jamais tu as une question, n’hésite pas à m’envoyer un mail à
|
||
[[mailto:lucien@phundrak.com][lucien@phundrak.com]]. Si jamais tu trouves une erreur dans ce que je
|
||
viens de dire dans ce tutoriel, ou si tu as une suggestion, c’est
|
||
justement le moment de mettre en pratique ce que tu as lu un peu plus
|
||
haut et d’ouvrir une issue sur Github sur le [[https://github.com/Phundrak/tutoriel-git][dépôt de ce tutoriel]].
|
||
|
||
#+begin_html
|
||
<script defer src="https://commento.phundrak.com/js/commento.js"></script>
|
||
<div id="commento"></div>
|
||
#+end_html
|
||
|
||
** [EN] My YouTube subscriptions as an RSS feed :linux:dev:tutorial:
|
||
:PROPERTIES:
|
||
:EXPORT_FILE_NAME: youtube-subscriptions-rss
|
||
:EXPORT_DATE: 2022-02-04
|
||
:export_hugo_menu: :menu "main"
|
||
:END:
|
||
*** The Problem
|
||
I’m sure you’ve been in the same situation before: you go on YouTube
|
||
because you want to watch a video, maybe two, from your subscriptions.
|
||
You open the first one. Oh great, an unskippable fifteen seconds ad.
|
||
And another one! OK, the video starts. It gets cut a couple of times
|
||
by other ads of varying length. Oh but what’s this? This recommended
|
||
video looks nice! And before you know it, your whole afternoon and
|
||
evening went by painfully watching videos on YouTube’s atrocious video
|
||
player. You lost focus.
|
||
|
||
*** My Solution: mpv + RSS
|
||
Wouldn’t it be nice if it were possible to watch these videos with a
|
||
full fledged video player over which you have complete control? Which
|
||
could be customized to your heart’s content? Which won’t secretly
|
||
track what you watch?
|
||
|
||
Oh right, [[https://mpv.io/][mpv]]! It supports most video formats you can think of, and
|
||
thanks to its interoperability with [[https://github.com/ytdl-org/youtube-dl][youtube-dl]], you can also watch
|
||
videos from [[https://ytdl-org.github.io/youtube-dl/supportedsites.html][an extremely wide variety of websites]]! So why not YouTube?
|
||
|
||
Now, the question is how to get rid of YouTube’s interface. The answer
|
||
is actually quite simple: let’s use an RSS feed. With the RSS feeds
|
||
from YouTube, you will receive in your RSS reader the link of the
|
||
video with its thumbnail and its description. You can then copy from
|
||
there the link and open it with mpv with a command like this:
|
||
#+begin_src bash
|
||
mpv "https://www.youtube.com/watch?v=xym2R6_Qd7c"
|
||
#+end_src
|
||
|
||
**** Channel RSS
|
||
Now the question is how to get the RSS feed of a channel? The answer
|
||
is quite simple. The base URL for a YouTube channel RSS feed is
|
||
~https://www.youtube.com/feeds/videos.xml?channel_id=~ to which you
|
||
simply have to add the channel ID. For instance, if you want to follow
|
||
Tom Scott with this, you simply have to extract the part of the
|
||
channel after ~/channel/~ in his URL and append it to the URL mentioned
|
||
above, and TADAH! you get an RSS feed to his channel!
|
||
#+begin_src text
|
||
https://www.youtube.com/feeds/videos.xml?channel_id=UCBa659QWEk1AI4Tg--mrJ2A
|
||
#+end_src
|
||
|
||
Be careful to select the channel ID only if it is after a ~/channel/~
|
||
though! The part that is after a ~/c/~ will not work. If you end up on
|
||
the URL ~https://www.youtube.com/c/TomScottGo~, simply click on a random
|
||
video, then click on the channel’s name. This should bring you back to
|
||
the channel but with an important difference: the URL is now
|
||
~https://www.youtube.com/channel/UCBa659QWEk1AI4Tg--mrJ2A~.
|
||
|
||
The thing that is really nice with this setup is you don’t really need
|
||
to actually subscribe to a channel, your RSS feed already does that
|
||
for you! And with lots of RSS feed readers, you can categorize your
|
||
different feeds, meaning you can even categorize your subscriptions!
|
||
|
||
**** Playlist RSS
|
||
It is also possible to follow not only a channel but a playlist of
|
||
videos. For that, you will instead use
|
||
~https://www.youtube.com/feeds/videos.xml?playlist_id=~ as your base URL
|
||
to which you will add the ID of the playlist you want to follow. For
|
||
instance, with Tom Scott’s playlist for Citation Needed Season 7, the
|
||
URL of the playlist is
|
||
~https://www.youtube.com/playlist?list=PL96C35uN7xGI15-QbtUD-wJ5-G8oBI-tG~,
|
||
which means you need to keep the ~PL96C35uN7xGI15-QbtUD-wJ5-G8oBI-tG~
|
||
and put it into the URL like so:
|
||
#+begin_src text
|
||
https://www.youtube.com/feeds/videos.xml?playlist_id=PL96C35uN7xGI15-QbtUD-wJ5-G8oBI-tG
|
||
#+end_src
|
||
|
||
*** Which RSS reader to go with?
|
||
If you know me, you’ll know I am extremely biaised towards Emacs, so
|
||
of course I’ll recommend Elfeed to any Emacs user ([[https://config.phundrak.com/emacs#Packages-Configuration-Applications-Elfeedoip0fl6184j0][my relevant
|
||
configuration is here]]). I even wrote an advice around
|
||
~elfeed-show-visit~ to ensure YouTube videos are open with mpv instead
|
||
of my web browser.
|
||
|
||
If you’re not into Emacs, or not /that/ into Emacs, you can also try
|
||
other alternatives such as [[https://gitlab.com/news-flash/news_flash_gtk][NewsFlash]], a very nice RSS reader written
|
||
in GTK for Linux –I may not always agree with DistroTube, but he made
|
||
a [[https://www.youtube.com/watch?v=KBAmviddh4A][very nice video]] presenting this piece of software. (Remember,
|
||
right-click and then ~mpv "the url here"~!)
|
||
|
||
The [[https://apps.nextcloud.com/apps/news][News app]] for Nextcloud is also very neat, I recommend you using it.
|
||
|
||
You can also get your RSS feed in your terminal with [[https://newsboat.org/][Newsboat]]. Not
|
||
really my cup of tea, but I can see why some people enjoy it.
|
||
|
||
*** Improving a bit the mpv tooling
|
||
You might have heard it, but youtube-dl hasn’t been doing great
|
||
recently. The tool is becoming slow and it lacks quite a few features
|
||
it could really benefit from. While it is important to acknowledge its
|
||
historical importance, I think it is now time to move on, and its
|
||
successor shall be [[https://github.com/yt-dlp/yt-dlp][yt-dlp]]. In my experience, this youtube-dl fork is
|
||
much faster than youtube-dl itself on top of providing additional
|
||
features such as [[https://github.com/yt-dlp/yt-dlp#sponsorblock-options][SponsorBlock integration]].
|
||
|
||
How do you replace youtube-dl with yt-dlp then? If you use ArchLinux
|
||
or one of its derivates (I hope not Manjaro though), you can simply
|
||
install ~yt-dlp-drop-in~ from the AUR.
|
||
#+begin_src bash
|
||
paru -S yt-dlp-drop-in
|
||
# or if you prefer yay
|
||
yay -S yt-dlp-drop-in
|
||
# or whichever AUR helper you prefer, as long as it is NOT yaourt
|
||
#+end_src
|
||
|
||
If you are not an ArchLinux user, check out [[https://www.funkyspacemonkey.com/replace-youtube-dl-with-yt-dlp-how-to-make-mpv-work-with-yt-dlp][this article]], it will help
|
||
you.
|