hgbook
view es/hgext.tex @ 482:7b90444b3905
added more notes about stuff to check once the translation is finished
| author | Javier Rojas <jerojasro@devnull.li> |
|---|---|
| date | Mon Jan 05 00:33:02 2009 -0500 (2009-01-05) |
| parents | 6d4465f04bb7 |
| children | 41a15a68582d |
line source
1 \chapter{Añadir funcionalidad con extensiones}
2 \label{chap:hgext}
4 A pesar de que el corazón de Mercurial es muy completo desde el punto
5 de vista de funcionalidad, carece de características rimbombantes
6 deliberadamente. Esta aproximación de preservar la simplicidad
7 mantiene el programa sencillo tanto para mantenedores como para
8 usuarios.
10 Si embargo Mercurial no le cierra las posibilidades a un conjunto
11 inflexible de órdenes: usted puede añadir características como
12 \emph{extensiones} (aveces llamadas \emph{añadidos}\ndt{plugins}). Ya
13 hemos discutido algunas de estas extensiones en capítulos anteriores:
14 \begin{itemize}
15 \item La sección~\ref{sec:tour-merge:fetch} cubre la extensión
16 \hgext{fetch}; que combina jalar cambios y fusionarlos con los
17 cambios locales en una sola orden: \hgxcmd{fetch}{fetch}.
18 \item En el capítulo~\ref{chap:hook}, cubrimos muchas extensiones que
19 son útiles en funcionalidades relacionadas con ganchos: Los
20 \hgext{acl} añaden listas de control de acceso; \hgext{bugzilla}
21 añade integración con el sistema de seguimiento de fallos Bugzilla; y
22 \hgext{notify} envía notificaciones por correo de nuevos cambios.
23 \item La extensión de administración de parches MQ es tan invaluable
24 que amerita dos capítulos y un apéndice por sí misma.
25 El capítulo~\ref{chap:mq} cubre lo básico; el
26 capítulo~\ref{chap:mq-collab} discute temas avanzados; y el
27 apéndice~\ref{chap:mqref} muestra en detalle cada orden.
28 \end{itemize}
30 En este capítulo cubriremos algunas extensiones adicionales
31 disponibles para Mercurial, y daremos un vistazo a la maquinaria que
32 necesita conocer en caso de que desee escribir una extensión.
33 \begin{itemize}
34 \item En la sección~\ref{sec:hgext:inotify}, discutiremos la
35 posibilidad de mejorar el desempeño \emph{en gran medida} con la extensión
36 \hgext{inotify}.
37 \end{itemize}
39 \section{Mejorar el desempeño con la extensión \hgext{inotify}}
40 \label{sec:hgext:inotify}
42 ¿Desea lograr que las operaciones más comunmente usadas de Mercurial se
43 ejecuten centenas de veces más rápido? ¡A leer!
45 Mercurial tiene gran desempeño bajo circunstancias normales. Por
46 ejemplo, cuando ejecuta la orden \hgcmd{status}, Mercurial tiene que
47 revisar casi todos los ficheros y directorios en su repositorio de
48 forma que pueda desplegar el estado de los ficheros. Muchas otras
49 órdenes tienen que hacer tal trabajo tras bambalinas; por ejemplo la
50 orden \hgcmd{diff} usa la maquinaria de estado para evitar hacer
51 operaciones de comparación costosas en ficheros que obviamente no han
52 cambiado.
54 Dado que obtener el estado de los ficheros es crucial para obtener
55 buen desempeño, los autores de Mercurial han optimizado este código en
56 la medida de lo posible. Sin embargo, no puede obviarse el hecho de
57 que cuando ejecuta \hgcmd{status}, Mercurial tendrá que hacer por lo
58 menos una costosa llamada al sistema por cada archivo administrado
59 para determinar si ha cambiado desde la última vez que se consignó.
60 Para un repositorio suficientemente grande, puede tardar bastante
61 tiempo.
63 Para mostrar en números la magnitud de este efect, creé un repositorio
64 que contenía 150.000 archivos administrador. Tardó diez segundos para
65 ejecutar \hgcmd{status}, a pesar de que \emph{ninguno} de los ficheros
66 había sido modificado.
68 Muchos sistemas operativos modernos contienen una facilidad de
69 notificación de archivos. Si un programa se registra con un servicio
70 apropiado, el sistema operativo le notificará siempre que un fichero
71 de interés haya sido creado, modificado o borrado. En sistemas Linux,
72 el componente del núcleo que lo hace se llama \texttt{inotify}.
74 La extensión \hgext{inotify} habla con el componente \texttt{inotify}
75 del núcleo para optimizar las órdenes de \hgcmd{status}. La extensión
76 tiene dos componentes. Un daemonio está en el fondo recibiendo
77 notificaciones del subsistema \texttt{inotify}. También escucha
78 conexiones de una orden regular de Mercurial. La extensión modifica
79 el comportamiento de Mercurial de tal forma que, en lugar de revisar
80 el sistema de ficheros, le pregunta al daemonio. Dado que el daemonio
81 tiene información perfecta acerca del estado del repositorio, puede
82 responder instantáneamente con el resultado, evitando la necesidad de
83 revisar cada directorio y fichero del repositorio.
85 Retomando los diez segundos que medí al ejecutar la orden
86 \hgcmd{status} de Mercurial sobre un repositorio de 150.000
87 ficheros. Con la extensión \hgext{inotify} habilitada, el tiempo se
88 disipó a 0.1~seconds, un factor \emph{cien veces} más rápido.
90 Antes de continuar, tenga en cuenta algunos detalles:
91 \begin{itemize}
92 \item La extensión \hgext{inotify} es específica de Linux. Porque se
93 enlaza directamente con el subsistema \texttt{inotify} del núcleo
94 Linux, no funciona en otros sistemas operativos.
95 \item Debería funcionar en cualquier distribución Linux a partir de
96 comienzos del 2005. Las distribuciones más antiguas deben tener un
97 kernel sin \texttt{inotify}, o una versión de \texttt{glibc} que no
98 tiene necesariamente el soporte para la interfaz.
99 \item No todos los sistemas de ficheros pueden usarse con la extensión
100 \hgext{inotify}. Los sistemas de ficheros tales como NFS no lo
101 soportan, por ejemplo, si está corriendo Mercurial en vaios
102 sistemas, montados todos sobre el mismo sistema de ficheros en red.
103 El sistema \texttt{inotify} del kernel no tiene forma de saber
104 acerca de los cambios hechos en otro sistema. La mayoría de
105 sistemas de ficheros locales (p.e.~ext3, XFS, ReiserFS) deberían
106 funcionar bien.
107 \end{itemize}
109 Hacia mayo de 2007 la extensión \hgext{inotify} no venía de forma
110 predeterminada en Mercurial\ndt{Desde el 2008 para kernels 2.6 viene
111 en Mercurial, pero no está activada de forma predeterminada}, y es
112 un poco más compleja de activar que otras extensiones. Pero la mejora
113 en el desempeño bien vale la pena!
115 La extensión venía en dos partes: un conjunto de parches al código
116 fuente de Mercurial, y una librería de interfaces de Python hacia el
117 subsistema \texttt{inotify}.
118 \begin{note}
119 Hay \emph{dos} librerías de enlace de Python hacia \texttt{inotify}.
120 Una de ellas se llama \texttt{pyinotify}, y en algunas
121 distribuciones de Linux se encuentra como \texttt{python-inotify}.
122 Esta es la que \emph{no} necesita, puesto que tiene muchos fallos,
123 y es ineficiente para ser práctica.
124 \end{note}
125 Para comenzar, es mejor tener una copia de Mercurial funcional
126 instalada:
127 \begin{note}
128 Si sigue las instrucciones a continuación, estará
129 \emph{reemplazando} y sobreescribiendo cualquier instalación previa
130 de Mercurial que pudiera tener, con el código de Mercurial ``más
131 reciente y peligrosa''. No diga que no se le advirtio!
132 \end{note}
133 \begin{enumerate}
134 \item Clone el repositorio de interfaz entre Python e
135 \texttt{inotify}. Ármelo e instálelo:
136 \begin{codesample4}
137 hg clone http://hg.kublai.com/python/inotify
138 cd inotify
139 python setup.py build --force
140 sudo python setup.py install --skip-build
141 \end{codesample4}
142 \item Clone el repositorio \dirname{crew} de Mercurial. Clone el
143 repositorio de parches de \hgext{inotify} de forma tal que las colas
144 de Mercurial puedan aplicar los parches sobre el repositorio \dirname{crew}.
145 \begin{codesample4}
146 hg clone http://hg.intevation.org/mercurial/crew
147 hg clone crew inotify
148 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches
149 \end{codesample4}
150 \item Asegúrese de instalar la extensión Colas de Mercurial
151 \hgext{mq} y que estén habilitadas. Si nunca ha usado MQ, lea la
152 sección~\ref{sec:mq:start} para poder comenzar rápidamente.
153 \item Vaya al repositorio de \dirname{inotify} y aplique todos los
154 parches de \hgext{inotify} con la opción \hgxopt{mq}{qpush}{-a} de
155 la orden \hgxcmd{mq}{qpush}.
156 \begin{codesample4}
157 cd inotify
158 hg qpush -a
159 \end{codesample4}
160 Si obtiene un mensaje de error de \hgxcmd{mq}{qpush}, no debería
161 continuar. Mejor pida ayuda.
162 \item Arme e instale la versión parchada de Mercurial.
163 \begin{codesample4}
164 python setup.py build --force
165 sudo python setup.py install --skip-build
166 \end{codesample4}
167 \end{enumerate}
168 Una vez que haya armado una versión funcional parchada de Mercurial,
169 todo lo que necesita es habilitar la extensión \hgext{inotify}
170 colocando una entrada en su \hgrc.
171 \begin{codesample2}
172 [extensions]
173 inotify =
174 \end{codesample2}
175 Cuando la extensión \hgext{inotify} esté habilitada, Mercurial
176 iniciará transparente y automáticamente el daemonio de estado la
177 primera vez que ejecute un comando que requiera estado del
178 repositorio. Ejecuta un daemoniot de estado por repositorio.
180 El daemonio de estado se inicia silenciosamente y se ejecuta en el
181 fondo. Si mira a la lista de procesos en ejecución después de
182 habilitar la extensión \hgext{inotify} y ejecuta unos pocos comandos
183 en diferentes repositorios, verá que hay algunos procesos de
184 \texttt{hg} por ahí, esperando actualizaciones del kernel y
185 solicitudes de Mercurial.
187 La primera vez que ejecuta un comando de Mercurial en un repositorio
188 cuando tiene la extensión \hgext{inotify} habilitada, correrá casi con
189 el mismo desempeño que una orden usual de Mercurial. Esto es debido a
190 que el estado del daemonio necesita aplicar una búsqueda normal sobre
191 el estado para poder tener una línea de partida frente a la cual
192 aplicar posteriormente actualizaciones del núcleo. De todas formas,
193 \emph{todo} comando posterior que haga cualquier clase de revisión del
194 estado debería ser notablemente más rápido en repositorios con incluso
195 un tamaño modesto. Aún mejor, a medida que su repositorio sea más
196 grande, mejor desempeño verá. El daemonio \hgext{inotify} hace
197 operaciones de estado de forma casi instantánea en repositorios de
198 todos los tamaños!
200 Si lo desea, puede iniciar manualmente un daemonio de estado con la orden
201 \hgxcmd{inotify}{inserve}. Esto le da un control un poco más fino
202 acerca de cómo debería ejecutarse el daemonio. Esta orden solamente
203 estará disponible cuando haya habilitado la extensión \hgext{inotify}.
205 Cuando esté usando la extensión \hgext{inotify},
206 \emph{no debería ver diferencia} en el comportamiento de Mercurial,
207 con la única excepción de que los comandos relacionados con el estado
208 deberían ejectuarse mucho más rápido que como solían hacerlo. Debería
209 esperar específicamente que las órdenes no deberían ofrecer salidas
210 distintas; ni ofrecer resultados diferentes. Si alguna de estas
211 situaciones ocurre, por favor reporte el fallo.
213 \section{Soporte flexible de diff con la extensión \hgext{extdiff}}
214 \label{sec:hgext:extdiff}
216 La orden predeterminada \hgcmd{diff} de Mercurial despliega diffs en
217 texto plano unificadas.
218 \interaction{extdiff.diff}
219 Si dese emplear una herramienta externa para desplegar las
220 modificaciones, querrá usar la extensión \hgext{extdiff}. Esta le
221 permitirá usar por ejemplo una herramienta gráfica de diff.
223 La extensión \hgext{extdiff} viene con Mercurial, y es fácil
224 configurarl. En la sección \rcsection{extensions} de su \hgrc,
225 basta con añadir una entrada de una línea para habilitar la extensión.
226 \begin{codesample2}
227 [extensions]
228 extdiff =
229 \end{codesample2}
230 Esto introduce una orden llamada \hgxcmd{extdiff}{extdiff}, que de
231 forma predeterminada usa su orden del sistema \command{diff} para
232 generar un diff unificado de la misma forma que lo hace el comando
233 predeterminado \hgcmd{diff}.
234 \interaction{extdiff.extdiff}
235 El resultado no será exactamente el mismo que con la orden interna
236 \hgcmd{diff}, puesto que la salida de \command{diff} varía de un
237 sistema a otro, incluso pasando las mismas opciones.
239 Como lo indican las líneas``\texttt{making snapshot}'', la orden
240 \hgxcmd{extdiff}{extdiff} funciona creando dos instantáneas de su
241 árbol de fuentes. La primera instantánea es la revisión fuente; la
242 segunda es la revisión objetivo del directorio de trabajo. La orden
243 \hgxcmd{extdiff}{extdiff} genera estas instantáneas en un directorio
244 temporal, pasa el nombre de cada directorio a un visor de diffs
245 temporal y borra los directorios temporales. Por cuestiones de
246 eficiencia solamente genera instantáneas de los directorios y ficheros
247 que han cambiado entre dos revisiones.
249 Los nombres de los directorios de instantáneas tienen los mismos
250 nombres base de su repositorio. Si su repositorio tiene por ruta
251 \dirname{/quux/bar/foo}, \dirname{foo} será el nombre de cada
252 instantánea de directorio. Cada instantánea de directorio tiene sus
253 identificadores de conjuntos de cambios al final del nombre en caso de
254 que sea apropiado. Si una instantánea viene de la revisión
255 \texttt{a631aca1083f}, el directorio se llamará
256 \dirname{foo.a631aca1083f}. Una instantánea del directorio de trabajo
257 no tendrá el identificador del conjunto de cambios, y por lo tanto
258 será solamente \dirname{foo} en este ejemplo. Para ver cómo luce en
259 la práctica, veamos de nuevo el ejemplo \hgxcmd{extdiff}{extdiff}
260 antes mencionado. Tenga en cuenta que los diffs tienen los nombres de
261 las instantáneas de directorio dentro de su encabezado.
263 La orden \hgxcmd{extdiff}{extdiff} acepta dos opciones importantes.
264 La opción \hgxopt{extdiff}{extdiff}{-p} le permite elegir un programa
265 para ver las diferencias, en lugar de \command{diff}. Con la opción
266 \hgxopt{extdiff}{extdiff}{-o} puede cambiar las opciones que
267 \hgxcmd{extdiff}{extdiff} pasa a tal programa(de forma predeterminada
268 las opciones son``\texttt{-Npru}'', que tienen sentido únicamente si
269 está usando \command{diff}). En otros aspectos, la orden
270 \hgxcmd{extdiff}{extdiff} actúa de forma similar a como lo hace la
271 orden \hgcmd{diff} de Mercurial: usted usa los mismos nombres de
272 opciones, sintaxis y argumentos para especificar las revisiones y los
273 ficheros que quiere, y así sucesivamente.
275 Por ejemplo, para ejecutar la orden usual del sistema \command{diff},
276 para lograr que se generen diferencias de contexto (con la opción
277 \cmdopt{diff}{-c}) en lugar de diferencias unificadas, y cinco líneas
278 de contexto en lugar de las tres predeterminadas(pasando \texttt{5}
279 como argumento a la opción \cmdopt{diff}{-C}).
280 \interaction{extdiff.extdiff-ctx}
282 Es sencillo lanzar unas herramienta usual de diferencias. Para lanzar
283 el visor \command{kdiff3}:
284 \begin{codesample2}
285 hg extdiff -p kdiff3 -o ''
286 \end{codesample2}
288 Si su orden para visualizar diferencias no puede tratar con
289 directorios, puede usar un poco de scripting para lograrlo. Un
290 ejemplo de un script con la extensión \hgext{mq} junto con la orden
291 \command{interdiff} está en la sección~\ref{mq-collab:tips:interdiff}.
293 \subsection{Definición de alias de comandos}
295 Acordarse de todas las opciones de las órdenes
296 \hgxcmd{extdiff}{extdiff} y el visor de diferencias de su preferencia
297 puede ser dispendioso, y por lo tanto la extensión \hgext{extdiff} le
298 permite definir \emph{nuevas} órdenes que invocarán su visor de
299 diferencias con las opciones exactas.
301 Basta con editar su fichero \hgrc, y añadir una sección llamada
302 \rcsection{extdiff}. Dentro de esta sección puede definir varias
303 órdenes. Mostraremos como añadir la orden \texttt{kdiff3}. Después de
304 definido, puede teclear ``\texttt{hg kdiff3}'' y la extensión a
305 \hgext{extdiff} ejecutará la orden \command{kdiff3}.
306 \begin{codesample2}
307 [extdiff]
308 cmd.kdiff3 =
309 \end{codesample2}
310 Si deja vacía la porción derecha de la definición, como en el ejemplo,
311 la extensión \hgext{extdiff} usa el nombre de la orden se definirá
312 como el nombre del programa externo a ejecutar. Pero tales nombres no
313 tienen por qué ser iguales. Definimos ahora la orden llamada
314 ``\texttt{hg wibble}'', que ejecuta \command{kdiff3}.
315 \begin{codesample2}
316 [extdiff]
317 cmd.wibble = kdiff3
318 \end{codesample2}
320 También puede especificar las opciones predeterminadas con las cuales
321 desea invocar el visor de diferencias. Se usa el prefijo ``\texttt{opts.}'',
322 seguido por el nombre de la orden a la cual se aplican las opciones.
323 En este ejemplos se define la orden ``\texttt{hg vimdiff}'' que
324 ejecuta la extensión \texttt{DirDiff} del editor \command{vim}.
325 \begin{codesample2}
326 [extdiff]
327 cmd.vimdiff = vim
328 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'
329 \end{codesample2}
331 \section{Uso de la extensión \hgext{transplant} para seleccionar}
332 \label{sec:hgext:transplant}
334 Need to have a long chat with Brendan about this.
336 \section{Enviar cambios vía correo electrónico con la extensión \hgext{patchbomb}}
337 \label{sec:hgext:patchbomb}
339 Varios proyectos tienen la cultura de ``revisión de cambios'', en la
340 cual la gente envía sus modificaciones a una lista de correo para que
341 otros las lean y comenten antes de consignar la versión final a un
342 repositorio compartido. Algunos proyectos tienen personas que actúan
343 como cancerberos; ellos aplican los cambios de otras personas a un
344 repositorio para aquellos que no tienen acceso.
346 Mercurial facilita enviar cambios por correo para revisión o
347 aplicación gracias a su extensión \hgext{patchbomb}. La extensión es
348 tan popular porque los cambios se formatean como parches y es usual
349 que se envía un conjunto de cambios por cada correo. Enviar una gran
350 cantidad de cambios por correos se llama por tanto ``bombardear'' el
351 buzón de entrada del destinatario, de ahí su nombre ``bombardeo de
352 parches''.
354 Como es usual, la configuración básica de la extensión
355 \hgext{patchbomb} consta de una o dos líneas en su \hgrc.
356 \begin{codesample2}
357 [extensions]
358 patchbomb =
359 \end{codesample2}
360 Cuando haya habilitado la extensión, dispondrá de una nueva orden,
361 llamada \hgxcmd{patchbomb}{email}.
363 La forma mejor y más segura para invocar la orden
364 \hgxcmd{patchbomb}{email} es ejecutarla \emph{siempre} con la opción
365 \hgxopt{patchbomb}{email}{-n}; que le mostrará lo que la orden
366 \emph{enviaría}, sin enviar nada. Una vez que haya dado un vistazo a
367 los cambios y verificado que está enviando los correctos, puede volver
368 a ejecutar la misma orden, sin la opción \hgxopt{patchbomb}{email}{-n}.
370 La orden \hgxcmd{patchbomb}{email} acepta la misma clase de sintaxis
371 de revisiones como cualquier otra orden de Mercurial. Por ejemplo,
372 enviará todas las revisiones entre la 7 y la \texttt{punta}, inclusive.
373 \begin{codesample2}
374 hg email -n 7:tip
375 \end{codesample2}
376 También puede especificar un \emph{repositorio} para comparar. Si
377 indica un repositoro sin revisiones, la orden \hgxcmd{patchbomb}{email}
378 enviará todas las revisiones en el repositorio local que no están
379 presentes en el repositorio remoto. Si especifica revisiones
380 adicionalmente o el nombre de una rama(la última con la opción
381 \hgxopt{patchbomb}{email}{-b}), respetará las revisiones enviadas.
383 Ejecutar la orden \hgxcmd{patchbomb}{email} sin los nombres de
384 aquellas personas a las cuales desea enviar el correo es completamente
385 seguro: si lo hace, solicitará tales valores de forma interactiva.
386 (Si está usando Linux o un sistema tipo Unix, tendrá capacidades
387 estilo--\texttt{readline} aumentadas cuando ingrese tales encabezados,
388 lo cual es sumamente útil.)
390 Cuando envíe una sola revisión, la orden \hgxcmd{patchbomb}{email}
391 de forma predeterminada usará la primera línea de descripción del
392 conjunto de cambios como el tema del único mensaje que se enviará.
394 Si envía varias revisiones, la orden \hgxcmd{patchbomb}{email} enviará
395 normalmente un mensaje por conjunto de cambios. colocará como
396 prefacio un mensaje introductorio en el cual usted debería describir
397 el propósito de la serie de cambios que está enviando.
399 \subsection{Cambiar el comportamiento de las bombas de parches}
401 Cada proyecto tiene sus propias convenciones para enviar cambios en un
402 correo electrónico; la extensión \hgext{patchbomb} intenta acomodarse
403 a diferentes variaciones gracias a las opciones de la línea de órdenes:
404 \begin{itemize}
405 \item Puede escribir un tema para el mensaje introductorio en la línea
406 de órdenes con la opciń \hgxopt{patchbomb}{email}{-s}. Toma un
407 argumento: el tema del mensaje a usar.
408 \item Para cambiar el correo electrónico del campo del cual se
409 origina, use la opción \hgxopt{patchbomb}{email}{-f}. Toma un
410 argumento, el correo electrónico a usar.
411 \item El comportamiento predeterminado es enviar diferencias
412 unificadas (consulte la sección~\ref{sec:mq:patch} si desea una
413 descripción del formato), una por mensaje. Puede enviar un conjunto
414 binario\ndt{binary bundle} con la opción \hgxopt{patchbomb}{email}{-b}.
415 \item Las diferencias unificadas están precedidas por un encabezado de
416 metadatos. Puede omitirlo, y enviar diferencias sin adornos con la
417 opción \hgxopt{patchbomb}{email}{--plain}.
418 \item Las diferencias usualmente se envían ``en línea'', como parte
419 del cuerpo del mensaje con la descripción del parche. Que facilita a
420 a la mayor cantidad de lectores citar y responder partes de un diff,
421 dado que algunos clientes de correo solamente citarán la primera
422 parte MIME del cuerpo de un mensaje. Si prefiere enviar la
423 descripción y el diff en partes separadas del cuerpo, use la opción
424 \hgxopt{patchbomb}{email}{-a}.
425 \item En lugar de enviar mensajes de correo puede escribirlos a un
426 fichero con formato-\texttt{mbox}- con la opción
427 \hgxopt{patchbomb}{email}{-m}. La opción recibe un argumento, el
428 nombre del fichero en el cual escribir.
429 \item Si desea añadir un resumen con formato-\command{diffstat} en
430 cada parche, y uno como mensaje introductorio, use la opción
431 \hgxopt{patchbomb}{email}{-d}. La orden \command{diffstat}
432 despliega una tabla que contiene el nombre de cada fichero parchado,
433 el número de líneas afectadas, y un historgrama mostrando cuánto ha
434 sido modificado cada fichero. Lo cual ofrece a los lectores una
435 mirada cuantitativa de cuan complejo es el parche.
436 \end{itemize}
438 %%% Local Variables:
439 %%% mode: latex
440 %%% TeX-master: "00book"
441 %%% End: