<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
"../../../share/xml/freebsd45.dtd">
<article lang='es'>
<title><application>Perforce</application> en el contexto del desarrollo de &os;</title>
<articleinfo>
<authorgroup>
<author>
<firstname>Scott</firstname>
<surname>Long</surname>
<affiliation>
<address><email>scottl@FreeBSD.org</email>
</address>
</affiliation>
</author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.cvsup;
&tm-attrib.general;
</legalnotice>
<pubdate>$FreeBSD$</pubdate>
<releaseinfo>$FreeBSD$</releaseinfo>
</articleinfo>
<sect1 id="intro">
<title>Introducción</title>
<para>El proyecto &os; utiliza el sistema de control de versiones
<application>Perforce</application> para gestionar proyectos
experimentales que todavía no están listos para ser
incluidos en el repositorio principal de CVS.</para>
<sect2 id="resources">
<title>Disponibilidad, documentación y recursos</title>
<para>Aunque que el producto <application>Perforce</application>
es un producto comercial, el software cliente que se encarga de
interactuar con el servidor se distribuye libremente. Pueden
descargarse versiones binarias del mismo desde el
sitio web de <application>Perforce</application>:
<ulink url="http://www.perforce.com/perforce/loadprog.html"></ulink>.
</para>
<para>Existe un cliente gráfico, pero la mayoría de la gente
utiliza la aplicación de línea de órdenes,
<command>p4</command>. Este documento trata sobre el uso de
dicha herramienta para la línea de órdenes.</para>
<para>En
<ulink url="http://www.perforce.com/perforce/technical.html"></ulink>
encontrará documentación <quote>online</quote>
detallada.</para>
<para>Se recomienda encarecidamente leer la <quote>guía de
usuario</quote> y el <quote>manual de Perforce</quote>.
La aplicación <application>p4</application> dispone de una extensa
ayuda <quote>online</quote> a la que puede accederse mediante la
orden <command>p4 help</command>.</para>
<para>El servidor &os; <application>Perforce</application> se
encuentra en
<hostid role="fqdn">perforce.freebsd.org</hostid>,
puerto <literal>1666</literal>. Puede navegar por el
repositorio desde
<ulink url="http://perforce.freebsd.org"></ulink>.
Ciertas partes del repositorio se exportan automáticamente hacia
diversos servidores <application>CVSup</application>.</para>
</sect2>
</sect1>
<sect1 id="start">
<title>Los comienzos</title>
<para>El primer paso para utilizar
<application>Perforce</application> consiste en obtener una cuenta
en el servidor. Si ya dispone de una cuenta en
<hostid
role="domainname">FreeBSD.org</hostid>
entre en
<hostid
role="hostname">freefall</hostid>
y ejecute el siguiente comando utilizando una contraseña distinta
del acceso de su &os; o de cualquier otro mecanismo de
autenticación SSH:</para>
<screen>&prompt.user; <userinput>/usr/local/bin/p4newuser</userinput></screen>
<para>Por supuesto si no tiene una cuenta en
<hostid
role="domainname">FreeBSD.org</hostid>
necesitará coordinarse con su mentor.</para>
<para>El siguiente paso consiste en establecer las variables de
entorno que necesita <command>p4</command> y en verificar
que puede conectarse al servidor. Es necesario especificar la variable
<envar>P4PORT</envar> para realizar cualquier operación. Dicha
variable indica el servidor <application>Perforce</application>
con el que se va a trabajar. En el caso del Proyecto &os;, créela
con el siguiente valor:</para>
<screen>&prompt.user; <userinput>export P4PORT=perforce.freebsd.org:1666</userinput></screen>
<note>
<para>Los usuarios con acceso <quote>shell</quote> al
<quote>cluster</quote>
<hostid
role="domainname">FreeBSD.org</hostid>
pueden querer encapsular el protocolo cliente-servidor de
<application>Perforce</application> a través de un
túnel SSH, en cuyo caso la variable de arriba
debería establecerse al valor
<literal>localhost</literal>.</para>
</note>
<para>El servidor &os; también necesita que se establezcan las
variables <envar>P4PASSWD</envar> y <envar>P4USER</envar>. Utilice
el nombre de usuario y la contraseña anteriores del siguiente
modo:</para>
<screen>&prompt.user; <userinput>export P4USER=<replaceable>nombre_de_usuario</replaceable></userinput>
&prompt.user; <userinput>export P4PASSWD=<replaceable>contraseña</replaceable></userinput></screen>
<para>Compruebe que todo funciona mediante la siguiente
orden:</para>
<screen>&prompt.user; <userinput>p4 info</userinput></screen>
<para>A resultas de esta orden debería ver información
referente al servidor. Si no es así compruebe que
la variable <envar>P4PORT</envar> tiene el valor correcto.
</para>
</sect1>
<sect1 id="clients">
<title>Clientes</title>
<para>El sistema <application>Perforce</application> proporciona
acceso al repositorio y mantiene el estado del cliente de forma
individualizada. En términos de
<application>Perforce</application>, un cliente es una
especificación que asocia
<footnote><para>
Este término, que también puede traducirse como
asociar o asignar, suele aparecer en la jerga de la
administración de sistemas como
<quote>mapear</quote>.
</para></footnote>
ficheros y directorios desde el
repositorio hasta la máquina local. Cada usuario puede poseer
varios clientes, y cada cliente puede acceder a distintas partes
del repositorio (incluso a varias partes que se solapan entre sí).
El cliente también especifica el directorio raíz del
árbol de
directorios sobre el que se realiza la asociación y la
máquina
donde efectivamente está dicho árbol. Es por esto que
si pretende trabajar en varias máquinas tendrá que
usar varios clientes.
</para>
<para>Puede acceder a los clientes mediante
<command>p4 client</command>. Si se ejecuta esta orden sin
argumentos aparece una plantilla del cliente dentro de un
editor, permitiendo de esta forma crear un nuevo cliente. Los
campos importantes de esta plantilla se explican a
continuación:</para>
<variablelist>
<varlistentry>
<term><literal>Client:</literal></term>
<listitem>
<para>Este es el nombre de la especificación del cliente.
Puede ser cualquier cosa, pero debe ser una cadena única
dentro del servidor <application>Perforce</application>. Suelen
usarse nombres como
<literal><replaceable>nombre_de_usuario</replaceable>_<replaceable>nombre_de_máquina</replaceable></literal>,
que permite identificar fácilmente a los clientes cuando se
navega por ellos.
Por defecto hay ya un nombre, que se
corresponde con el nombre de la máquina.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>Description:</literal></term>
<listitem>
<para>Este campo suele consistir en un breve texto descriptivo
que ayude a identificar al cliente.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>Root:</literal></term>
<listitem>
<para>Se trata del directorio local que actuará como
directorio raíz para todos los ficheros dentro de la
asociación en el cliente.
Debe ser una localización única
dentro del sistema
de ficheros que no se solape con otros ficheros o clientes
<application>Perforce</application>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>Options:</literal></term>
<listitem>
<para>La mayoría de las opciones por defecto son correctas y
válidas para todo el mundo, aunque suele ser recomendable
comprobar que estén activadas las opciones
<option>compress</option> y <option>rmdir</option>
y que no tienen el prefijo <literal>no</literal>. Los
detalles de cada una de estas opciones están en la
documentación de <application>Perforce</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>LineEnd:</literal></term>
<listitem>
<para>Este parámetro gestiona las conversiones CR-LF y debe
dejarse tal cual salvo que sus necesidades específicas
requieran cambiarlo.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>View:</literal></term>
<listitem>
<para>Aquí es donde están las asociaciones de ficheros
servidor-a-local.
El valor por defecto es:</para>
<programlisting>//depot/... //<replaceable>cliente</replaceable>/...</programlisting>
<para>Esto asociará por completo el repositorio
<application>Perforce</application> al directorio
<filename class="directory">Root</filename>
del cliente. <emphasis>NO USE ESTE VALOR POR DEFECTO</emphasis>.
El repositorio de &os; es enorme e intentar asociarlo y
sincronizarse con dicho repositorio tardará muchísimo y
consumirá enormes recursos. Asocie
sólamente la sección del repositorio en la que va a
trabajar. Por ejemplo, hay un árbol para el proyecto
smpng en <filename
class="directory">//depot/projects/smpng</filename>. Una
asociación en ese caso sería algo así:</para>
<programlisting>//depot/projects/smpng/... //<replaceable>cliente</replaceable>/...</programlisting>
<para>Los <literal>...</literal> deben tomarse literalmente
tal cual están. Es un dialecto de
<application>Perforce</application> para decir <quote>este
directorio y todos los ficheros y directorios por debajo de
él.</quote>.</para>
<para>Una <quote>vista</quote> (View) puede contener múltiples
asociaciones. Vamos a suponer que quiere asociar los
árboles de SMPng
y de NFS. Su <quote>View</quote> sería algo
así:</para>
<programlisting>//depot/projects/smpng/... //<replaceable>cliente</replaceable>/smpng/...
//depot/projects/nfs/... //<replaceable>cliente</replaceable>/nfs/...</programlisting>
<para>Recuerde que <replaceable>cliente</replaceable> es el
nombre del cliente que se especificó en la sección
<literal>Client</literal>, pero en la sección
<literal>View</literal> además se utiliza para resolver al
directorio especificado en la sección
<literal>Root</literal>.</para>
<para>También tenga en cuenta que el mismo fichero o
directorio no puede asociarse más de una vez dentro de una
única vista. La orden del siguiente ejemplo no es correcta
y producirá resultados imprevistos:
</para>
<programlisting>//depot/projects/smpng/... //<replaceable>cliente</replaceable>/smpng-esto/...
//depot/projects/smpng/... //<replaceable>cliente</replaceable>/smpng-lo_otro/...</programlisting>
<para>Las <quote>vistas</quote> son la parte compleja del proceso de
aprendizaje de <application>Perforce</application>, así que
no tenga miedo de hacer tantas preguntas como estime
oportunas.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Puede listar los clientes existentes mediante
<command>p4 clients</command>. Puede listarlos sin que sufran
modificaciones mediante <command>p4 client -o
<replaceable>nombre_cliente</replaceable></command>.</para>
<para>Siempre que se interactue con ficheros en
<application>Perforce</application> la variable de entorno
<envar>P4CLIENT</envar> debe contener al nombre del cliente que
se está utilizando, es decir:</para>
<screen>&prompt.user; <userinput>export P4CLIENT=<replaceable>nombredemicliente</replaceable></userinput></screen>
<para>Fíjese en que las asociaciones del cliente en el repositorio
no son exclusivos; varios clientes pueden estar asociados en la
misma zona del respositorio.
Esto permite el trabajo en equipo sobre el mismo
código, permitiendo que distintas personas accedan y
modifiquen la misma parte del respositorio.
</para>
</sect1>
<sect1 id="syncing">
<title>Sincronizaciones</title>
<para>Una vez definida la especificación del cliente y una vez
establecida la variable de entorno <envar>P4CLIENT</envar>, el
siguiente paso consiste en recuperar los ficheros para el cliente en
cuestión desde el servidor hasta la máquina local.
Esto se realiza
con <command>p4 sync</command>, el cual indica a
<application>Perforce</application> que sincronice los ficheros
locales con los del repositorio. La primera vez que se ejecuta
descargará todos los ficheros. Las siguientes ejecuciones
sólo descargarán aquellos ficheros que hayan cambiado
desde la última ejecución de la orden.
Gracias a esto es posible sincronizar sus fuentes con
las de otras personas con las que esté trabajando.</para>
<para>Las operaciones de sincronización sólo
atañen a aquellos ficheros cuyas modificaciones han
sido transmitidas a <application>Perforce</application>.
Si se modifica o borra un fichero en local sin informar de ello
al servidor la ejecución de un
<quote>sync</quote> no reflejará dichos cambios. No obstante, la
ejecución de <command>p4 sync -f</command> sincrozará
incondicionalmente todos los ficheros, sin que importe su estado.
Esto resulta útil para solucionar problemas cuando se cree que el
árbol pueda haber sufrido algún tipo de
corrupción.</para>
<para>Puede sincronizarse parte del árbol o del cliente
especificando una ruta relativa a la orden <quote>sync</quote>.
Por ejemplo, para sincronizar sólo el directorio
<filename class="directory">ufs</filename>
del proyecto <literal>smpng</literal> ejecute lo
siguiente:</para>
<screen>&prompt.user; <userinput>cd <replaceable>raizdelproyecto</replaceable>/smpng</userinput>
&prompt.user; <userinput>p4 sync src/sys/ufs/...</userinput></screen>
<para>El uso de rutas locales relativas funciona en muchas otras
órdenes <command>p4</command>.</para>
</sect1>
<sect1 id="branches">
<title>Ramas</title>
<para>Una de las características más interesantes de
<application>Perforce</application> es la posibilidad de crear
ramas. Las ramas son muy sencillas de crear y también resulta muy
fácil mover cambios entre distintas ramas (como se verá
más
adelante). Las ramas también nos permiten realizar trabajos muy
experimentales dentro de un entorno de <quote>sandbox</quote>, sin
necesidad de tener que preocuparnos por las colisiones con otros
usuarios o por desestabilizar el árbol principal. Además,
las ramas
proporcionan el aislamiento necesario frente a los errores que se
cometen cuando se aprende a manejar el sistema
<application>Perforce</application>. Vistas estas ventajas es
lógico que cada proyecto disponga de su propia rama y
en &os; recomendamos encarecidamente este esquema.
También se recomienda la aplicación frecuente de los cambios
realizados.</para>
<para>El repositorio <application>Perforce</application> (conocido
como el <quote>depósito</quote>, o <quote>depot</quote> en
la jerga de <application>Perforce</application>)
es un único árbol plano. Se accede a cada fichero a
través de una
sencilla ruta bajo el directorio <filename
class="directory">//depot</filename>, tanto si se trata de un
fichero de nueva creación como si proviene de una
ramificación.
Esto supone una gran diferencia con respecto a sistemas como CVS,
donde cada rama se encuentra en la misma ruta que su rama padre.
En <application>Perforce</application> el servidor mantiene las
relaciones entre los ficheros padre e hijo, pero los
ficheros en sí están bajo sus propias rutas.</para>
<para>El primer para para crear una rama consiste en crear una
especificación de rama. Es similar a la especificación
de un cliente,
pero se crea mediante la orden <command>p4 branch
<replaceable>nombre_de_rama</replaceable></command>.</para>
<para>Veamos los campos más importantes:</para>
<variablelist>
<varlistentry>
<term><literal>Branch</literal></term>
<listitem>
<para>El nombre de la rama. Puede ser cualquier nombre, pero
debe ser único en el repositorio. La convención
que se usa en &os; es
<replaceable>nombre_de_usuario</replaceable>_<replaceable>nombre_del_proyecto</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>Description</literal></term>
<listitem>
<para>Puede poner aquí un texto simple que describa la
rama.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>View</literal></term>
<listitem>
<para>Esto es la asociación de la rama. En lugar de asociar
desde el <quote>depósito</quote> hacia la máquina local
como una asociación de cliente, se crea una asociación
entre la rama padre y la rama hija
dentro del <quote>depósito</quote>. Por ejemplo, puede
querer crear una rama del proyecto smpng. La asociación
resultaría en algo parecido a esto:</para>
<programlisting>//depot/projects/smpng/... //depot/projects/mi-super-smpng/...</programlisting>
<para>O puede crear una rama totalmente nueva a
partir de las fuentes de &os;:</para>
<programlisting>//depot/vendor/freebsd/... //depot/projects/mi-nuevo-proyecto/...</programlisting>
<para>Esto asociará el HEAD del árbol de &os; a su
nueva rama.</para>
</listitem>
</varlistentry>
</variablelist>
<para>La creación de la especificación de rama
únicamente graba la
especificación en sí misma dentro del servidor. No
modifica el <quote>depósito</quote> ni cambia
ningún fichero. El directorio que se declara en la rama
permanece vacío en el servidor hasta que se comience a
llenar.
</para>
<para>Para rellenar la rama primero debemos editar el cliente con
la orden <command>p4 client</command> y asegurarnos de que el
directorio de rama está asociado en el cliente. Puede ser
necesario añadir una línea <literal>View</literal>
como esta:</para>
<programlisting>//depot/projects/mi-nuevo-proyecto/... //<replaceable>micliente</replaceable>/mi-nuevo-proyecto/...</programlisting>
<para>El siguiente paso consiste en ejecutar <command>p4
integrate</command>, como se describe en la siguiente
sección.</para>
</sect1>
<sect1 id="Integrations">
<title>Integraciones</title>
<para><quote>Integración</quote> es el término que se utiliza
en <application>Perforce</application> para describir la acción de
mover cambios desde una parte del <quote>depósito</quote> a otra.
Se suele realizar junto con las órdenes creación y
mantenimiento de ramas. Una integración es necesaria cuando se
quiere rellenar inicialmente una rama y cuando se quieren mover cambios
realizados en la rama padre hacia la rama hija, o de la la rama hija
a la padre. Un caso muy común es la integración
periódica desde el árbol original de &os; hacia la rama
hija propia del usuario.
El servidor <application>Perforce</application>
mantiene el estado de los cambios en cada rama y sabe cuándo
hay cambios que pueden integrarse de una rama a otra.</para>
<para>La forma más común de hacer una integración
se muestra en la siguiente orden:
</para>
<screen>&prompt.user; <userinput>p4 integrate -b <replaceable>nombrederama</replaceable></userinput></screen>
<para><replaceable>nombrederama</replaceable> es el nombre que se
ha dado a la
especificación de rama, tal y como se explicó en la
sección anterior.
Esta orden indica a <application>Perforce</application> que
busque cambios en la rama padre que todavía no se hayan
aplicado a la rama hija. En base a los cambios encontrados se
prepara un listado de diferencias a aplicar. Si la integración
se realiza por primera vez sobre una rama (por ejemplo cuando se
realiza una operación de rellenado inicial) los ficheros
de la rama padre simplemente se copiarán en la ubicación
en la rama hija de la máquina local.</para>
<para>Una vez que la operación de integración ha finalizado
se debe ejecutar <command>p4 resolve</command>, que aplicará
los cambios y resolverá posibles conflictos.
Los conflictos puede surgir debido a
cambios que se solapan al encontrarse tanto en fichero de la rama
padre como en la copia del fichero de la rama hija. Normalmente no
suelen aparecer conflictos y <application>Perforce</application>
puede calcular rápidamente cómo unir los cambios.
Para ejecutar una operación de resolución
(<quote>resolve</quote>) utilice las siguientes órdenes:</para>
<screen>&prompt.user; <userinput>p4 resolve -as</userinput>
&prompt.user; <userinput>p4 resolve</userinput></screen>
<para>La primera invocación indica a
<application>Perforce</application> que una automáticamente los
cambios y que acepte aquellos ficheros que no den conflictos. La
segunda invocación permite inspeccionar cada fichero con conflictos
y resolver de forma manual dichas incompatiblidades.</para>
<para>Una vez hecha la integración de los ficheros llega el
momento de aplicar los cambios al repositorio. Para ello se
emplearemos la orden
<command>p4 submit</command>, cuyo uso se explica en la
siguiente sección.</para>
</sect1>
<sect1 id="submit">
<title>Aplicación de cambios en el repositorio</title>
<para>Los cambios que se han realizado en local se deben
aplicar en el contenido del servidor <application>Perforce</application>
para mayor seguridad frente a pérdidas y para que otras
personas puedan acceder a dichos cambios; esto se hace con la
orden <command>p4 submit</command>. Cuando se ejecuta esta
orden se abre una plantilla (<quote>submit template</quote>)
en el editor. &os; dispone de una platilla personalizada, de la
que a continuación se explican los campos más
importantes:</para>
<programlisting>Description:
<enter description here>
PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
MFP4 after:</programlisting>
<para>es decir</para>
<programlisting>Descripción:
<Introduzca una descripción>
PR:
Enviado por:
Revisado por:
Aprobado por:
Obtenido de:
MFP4 tras:</programlisting>
<para>Se considera una buena práctica proporcionar al menos dos o
tres frases que describan los cambios entregados. Debería
declarar aquí qué hacen dichos cambios, por qué
se han hecho de esa forma o qué problemas intenta resolver
con ellos. También
conviene explicar qué APIs cambian y qué otros efectos
secundarios pueden tener.
Este texto debe sustituir a la línea <literal><enter
description here></literal> que aparece en la plantilla. Debe
recubrir las líneas y comenzar cada línea con una
tabulación. Las etiquetas de más abajo son
específicas de &os; y puede eliminarlas si no resultan
útiles o apropiadas en su contexto.</para>
<programlisting>Files:</programlisting>
<para>Este campo se rellena automáticamente con todos los ficheros
que el cliente etiquetó en el servidor con estados de
adición, borrado, integración o edición.
Le aconsejamos que revise esta lista y elimine de ella los ficheros
que todavía no esten listos.</para>
<para>Una vez guardada la sesión de su editor tiene lugar la entrega
de los datos al servidor. Esto significa que las copias locales de
los ficheros entregados se enviarán al servidor. Si algo va
mal durante este proceso se cancelará la entrega y se
avisará al usuario de que la entrega se ha convertido en
una lista de cambios que deben corregirse y reenviarse. Las
entregas son atómicas, es decir, si un fichero falla
la entrega se cancela en su totalidad.</para>
<para>Los cambios efectuados en el servidor no pueden cancelarse
una vez hechos, pero sí que pueden cancelarse si, dentro
aún del editor, se sale de él sin cambiar el
texto del campo
<literal>Description</literal>. <application>Perforce</application>
se quejará la primera vez que intente salir y le
devolverá al editor. Si sale por segunda vez el editor
cancelará la operación. Devolver el repositorio
al estado anterior a un cambio ya efectuado es un proceso
muy complicado y no hay un procedimiento estándar, por lo
que depende del caso concreto.</para>
</sect1>
<sect1 id="editing">
<title>Edición</title>
<para>En el servidor se almacena y mantiene el estado de cada
fichero del cliente. Para evitar colisiones entre distintas
personas trabajando al mismo tiempo en el mismo fichero
<application>Perforce</application> presta atención a qué
ficheros están abiertos en modo de edición, y utiliza
esa información para poder gestionar posteriormente las
operaciones de entrega, las sincronizaciones y las
integraciones.</para>
<para>Para abrir un fichero para editarlo utilice <command>p4
edit</command> de la siguiente forma:</para>
<screen>&prompt.user; <userinput>p4 edit <replaceable>nombredefichero</replaceable></userinput></screen>
<para>Esto marca el fichero en el servidor con el estado de
edición, lo que permite entregar el fichero posteriormente
una vez realizados los cambios oportunos, o lo etiqueta como de
tratamiento especial cuando se está efectuando una
operación de integración o sincronización.
Tenga en cuenta que la edición no es exclusiva en
<application>Perforce</application>. Varias personas pueden tener
el mismo fichero en estado de edición (será
informado de ello si es necesario cuando ejecute
<command>edit</command>), pero podrá entregar sus cambios
incluso cuando haya otras personas que tengan ese fichero en estado
de edición.</para>
<para>Cuando alguien entregue un cambio de un fichero que usted
esté editando necesitará cotejar sus modificaciones
con las de la otra u otras personas para poder aplicar
correctamente sus modifaciones al repositorio. La forma más
sencilla de hacerlo es ejecutar
<command>p4 sync</command> o <command>p4 submit</command> y dejar
que el programa encuentre algún conflicto, y a
continuación
ejecutar <command>p4 resolve</command> para <quote>resolver</quote>
manualmente los conflictos y aceptar los cambios de la otra persona
en su copia del fichero. Hecho esto, utilice <command>p4
submit</command> para aplicar sus cambios en el
repositorio.</para>
<para>Si posee un fichero abierto para su edición y
quiere descartar los cambios y devolverlo a su estado
original ejecute
<command>p4 revert</command> de la siguiente forma:</para>
<screen>&prompt.user; <userinput>p4 revert <replaceable>nombredefichero</replaceable></userinput></screen>
<para>Esto resincroniza el fichero con el contenido del servidor y
elimina en el servidor el atributo de edición para ese fichero.
Se perderá cualquier cambio que haya hecho en local.
Esto resulta muy útil cuando se han efectuado una serie de
cambios en un determinado fichero y se decide posteriormente que
no se desean aplicar dichos cambios en el servidor.</para>
<para>Cuando se sincroniza un fichero se marca como sólo lectura en
el sistema de ficheros. Aunque se pueden sobreescribir fácilmente
dichos permisos se aplican para recordar al usuario de una forma
educada que para ello se debe utilizar <command>p4 edit</command>.
Los ficheros modificados en local pero que no están en
estado de edición pueden sobreescribirse al ejecutar
<command>p4 sync</command>.</para>
</sect1>
<sect1 id="changes">
<title>Cambios, descripciones e historial</title>
<para>Puede ver el historial de cambios realizados al
<quote>depósito</quote> de
<application>Perforce</application> puede consultarse mediante
<command>p4 changes</command>. Esta orden proporciona una breve
descripción de cada cambio, quién la realizó
y cúal es el número de
modificación. Si lo que se quiere son los detalles
de un cambio en concreto utilice
<command>p4 describe
<replaceable>numero_de_cambio</replaceable></command>. Esta orden
proporciona el <quote>log</quote> y los
<quote>diffs</quote> de dicho cambio.
Normalmente se utilizan las opciones <option>-du</option> o
<option>-dc</option> para generar <quote>diffs</quote> unificados o
contextuales, respectivamente, en lugar del formato
del <quote>diff</quote> nativo.</para>
<para><command>p4 filelog <replaceable>nombre_de_fichero</replaceable></command>
muestra el historial de un fichero, incluyendo todas sus modificaciones,
integraciones y ramas que contenga.</para>
</sect1>
<sect1 id="diffs">
<title><quote>diffs</quote></title>
<para>Existen dos formas de generar <quote>diffs</quote> de ficheros en
<application>Perforce</application>, bien entre cambios locales
que todavía no se han entregado o bien entre dos
árboles (o dentro de una misma rama) del
<quote>depósito</quote>. Estos <quote>diffs</quote>
se generan mediante órdenes distintas,
<option>diff</option> y <option>diff2</option>:</para>
<variablelist>
<varlistentry>
<term><command>p4 diff</command></term>
<listitem>
<para>Ese comando genera un <quote>diff</quote> entre los cambios
locales y los cambios de ficheros en estado de edición. Los
parámetros <option>-du</option> y <option>-dc</option>
permiten crear <quote>diffs</quote> unificados o contextuales,
respectivamente. También se puede establecer la variable
<envar>P4DIFF</envar> para que apunte a un
<quote>diff</quote> local. Le recomendamos encarecidamente
usar esta orden para revisar sus cambios antes de
aplicarlos en el servidor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>p4 diff2</command></term>
<listitem>
<para>Esta orden crea un <quote>diffs</quote> entre ficheros
dados en el <quote>depósito</quote>, o entre
ficheros especificados en una especificación de rama. La
operación tiene lugar en el servidor, así que
la variable <envar>P4DIFF</envar> no surte ningún efecto,
aunque las opciones <option>-du</option> y
<option>-dc</option> sí pueden usarse. Las dos formas de
esta orden son:</para>
<screen>&prompt.user; <userinput>p4 diff2 -b <replaceable>nombrederama</replaceable></userinput></screen>
<para>y</para>
<screen>&prompt.user; <userinput>p4 diff2 //depot/<replaceable>ruta1</replaceable> //depot/<replaceable>ruta2</replaceable></userinput></screen>
</listitem>
</varlistentry>
</variablelist>
<para>En todos los casos los <quote>diffs</quote> se muestran en la salida
estándar. Por desgracia <application>Perforce</application>
usa un formato de <quote>diffs</quote> que resulta ser ligeramente
incompatible con las herramientas Unix estándar
<command>diff</command> y <command>patch</command>. La utilización
de la variable <envar>P4DIFF</envar> para que apunte al verdadero
&man.diff.1; puede paliar este problema, o al menos en ciertos casos,
puesto sólo funciona con la orden
<command>p4 diff</command>. La salida de
<option>diff2</option> debe procesarse para que sea de alguna
utilidad (la opción <option>-u</option> de
<option>diff2</option> producirá <quote>diffs</quote>
unificados que serán <emphasis>más o menos
compatibles</emphasis>, pero no esto no incluye ficheros
nuevos o borrados. Este <quote>script</quote> puede serle
de utilidad para este <quote>proceso necesario</quote>:
<ulink
url="http://people.freebsd.org/~scottl/awkdiff"></ulink>.</para>
</sect1>
<sect1 id="add-rm-files">
<title>Añadir o eliminar ficheros</title>
<para>La integración de una rama hará que
se añadan ficheros existentes en el servidor en su
árbol, pero quizás sea necesario añadir
nuevos ficheros o eliminar alguno de los ya existentes.
Para añadir ficheros no tiene más que
crear el fichero y ejecutar
<command>p4 add</command> de la siguiente forma:</para>
<screen>&prompt.user; <userinput>p4 add <replaceable>nombredefichero</replaceable></userinput></screen>
<para>Si quiere añadir un árbol completo de ficheros
ejecute:</para>
<screen>&prompt.user; <userinput>find . -type f |xargs p4 add</userinput></screen>
<para>Al ejecutar <command>p4 submit</command> se copiarán los
ficheros al <quote>depósito</quote> del servidor.
Es muy importante añadir
sólo ficheros y no directorios. Si se añade
explícitamente un
directorio, <application>Perforce</application> lo tratará como
fichero, lo cual seguramente no es lo que usted tenía
previsto.</para>
<para>Borrar un fichero es igualmente sencillo mediante
<command>p4 delete</command>:</para>
<screen>&prompt.user; <userinput>p4 delete <replaceable>nombredefichero</replaceable></userinput></screen>
<para>Esta orden marcará el fichero para que sea borrado del
<quote>depósito</quote> la siguiente vez que se ejecute una
entrega.
También borrará la copia local del fichero, así que
sea cauteloso cuando la use.</para>
<para>Por supuesto que borrar un fichero no significa que se borre
realmente del repositorio.</para>
<para>Los ficheros borrados se pueden <quote>resucitar</quote>
mediante la sincronización con una versión
previa. La única forma de borrar de forma permanente un
fichero es mediante la orden <command>p4 obliterat</command>.
Dicha orden es irreversible y costosa, así que sólo
está al alcance del personal que administra
el repositorio.</para>
</sect1>
<sect1 id="working-with-diffs">
<title>El trabajo con <quote>diffs</quote></title>
<para>Algunas veces puede ser necesario aplicar un <quote>diff</quote>
al árbol
de <application>Perfoce</application> que provenga de otra
aplicación. Si se trata de un <quote>diff</quote>
de gran tamaño y que afecta a muchos ficheros, puede resultar
tedioso ejecutar manualmente <command>p4 edit</command> sobre cada
fichero. Hay un truco para hacerlo de una forma más sencilla.
En primer lugar, asegúrese de que no hay ficheros abiertos en su
cliente y de que su árbol está sincronizado y actualizado a la
última versión. A continuación aplique
sus cambios mediante las herramientas habituales, y forzando los
permisos de los ficheros en caso de ser necesario. Después
ejecute lo siguiente:</para>
<screen>&prompt.user; <userinput>p4 diff -se ... |xargs p4 edit</userinput>
&prompt.user; <userinput>p4 diff -sd ... |xargs p4 delete</userinput>
&prompt.user; <userinput>find . -type f |xargs p4 add</userinput></screen>
<para>La primera orden le dice a
<application>Perforce</application> que busque los ficheros que
han cambiado, incluso si no están abiertos. La segunda
orden le dice a <application>Perforce</application> que busque
los ficheros que no existen en la máquina local pero que
sí están en el servidor. La tercera orden intenta
añadir todos los ficheros que están en local. Es
un método de fuerza bruta, pero funciona bien porque
<application>Perforce</application> sólo añadirá
los ficheros que le resulten desconocidos. El resultado de estas
órdenes es un conjunto de ficheros abiertos para edición,
borrado o para ser añadidos, según el caso. Hecho
esto solo nos queda ejecutar
<command>p4 submit</command> para entregar los cambios.</para>
</sect1>
<sect1 id="renaming-files">
<title>Cambiar nombres de ficheros</title>
<para><application>Perforce</application> no dispone de una forma
predefinida de cambiar nombres a ficheros o de moverlos a otra parte
del árbol. Si se copia el fichero en
cuestión a una nueva ubicación mediante <command>p4
add</command>, y posteriormente <command>p4
delete</command> en la versión anterior, se obtiene
algo muy parecido a lo que se quería, pero tiene el
inconveniente de que no se preserva el historial de cambios
de ese fichero. Esto puede perjudicar futuras integraciones entre
padres e hijos. Hay otro método más recomendable,
que consiste en efectuar una integración dentro del
mismo árbol y de una sola vez. Veamos un ejemplo:</para>
<screen>&prompt.user; <userinput>p4 integrate -i <replaceable>ficheroprevio</replaceable> <replaceable>ficheronuevo</replaceable></userinput>
&prompt.user; <userinput>p4 resolve</userinput>
&prompt.user; <userinput>p4 delete <replaceable>ficheroprevio</replaceable></userinput>
&prompt.user; <userinput>p4 submit</userinput></screen>
<para>La integración fuerza a <application>Perforce</application> a
mantener un registro de las relaciones entre los nombres antiguos y
los nuevos, lo cual será muy útil en futuras
integraciones. La opción
<option>-i</option> indica que se trata de una integración
<quote>sin base</quote>, es decir, que no existe un historial de
ramas al que recurrir en la integración. Este
parámetro tiene sentido en el presente ejemplo, pero
no debería utilizarse en integraciones basadas en ramas.</para>
</sect1>
<sect1 id="freebsd-cvs-and-p4">
<title>Interacciones entre el CVS de &os; y Perforce</title>
<para>Los repositorios de
<application>Perforce</application> y de CVS de &os; están
completamente separados. No obstante, los cambios que se producen
en CVS se reflejan casi en tiempo real en
<application>Perforce</application>. Cada 2 minutos se pregunta al
servidor de CVS sobre cambios realizados en la rama HEAD, y dichos
cambios se entregan a <application>Perforce</application> dentro del
árbol <filename
class="directory">//depot/vendor/freebsd/...</filename>.
De este modo este árbol permite la ramificación y
la integración de proyectos derivados. Cualquier proyecto
que implique la modificación del código fuente de
&os; debería tener este árbol como su rama padre
(o rama <quote>abuela</quote>, dependiendo
de las necesidades concretas de cada proyecto), y deberían tener
lugar integraciones periódicas y sincronizaciones para que el
árbol esté en consonancia con el desarrollo de &os; y
evitar conflictos en la medida de lo posible.</para>
<para>El puente entre CVS y <application>Perforce</application> es
de un sólo sentido; los cambios del CVS se reflejarán en
<application>Perforce</application>, pero los cambios en
<application>Perforce</application> no se reflejarán en el CVS.
Si es necesario, se pueden exportar partes del repositorio de
<application>Perforce</application> al
<application>CVSup</application> y que así se puedan distribuir.
Por favor, contacte con los
administradores de <application>Perforce</application> de &os; si
ese es su caso.</para>
</sect1>
<sect1 id="offline-ops">
<title>Funcionamiento sin conexión de red</title>
<para>Uno de los inconvenientes de <application>Perforce</application> es
que supone que siempre es posible acceder al servidor a través
de la red. La mayoría de los estados, el historial y los
metadatos se almacenan en el servidor y no existe mecanismo alguno
para replicar el servidor como los hay en
CVS/<application>CVSup</application>. Es posible
ejecutar un servidor proxy, pero solamente ayuda un poco si se quiere
trabajar sin conexión al servidor.</para>
<para>La mejor forma de trabajar sin conexión de red es
comprobando que el cliente no tiene ningún fichero abierto y
que está totalmente sincronizado antes de dejar de estar
conectado.
Cuando se edite un fichero se deberán cambiar manualmente
los permisos a lectura-escritura. Cuando vuelva a estar
conectado ejecute la orden que se mostraba
en la <xref linkend="working-with-diffs"/> para
identificar automáticamente los ficheros que se han editado,
añadido o eliminado.
Es bastante común encontrarse con la sorpresa de que
<application>Perforce</application> ha sobreescrito un fichero
modificado en local que no se abrió en modo edición,
así que tenga especial cuidado con esto.</para>
</sect1>
<sect1 id="soc">
<title>Consideraciones finales para el <quote>Google Summer of Code</quote></title>
<para>La mayoría de los proyectos de &os; dentro del programa
<quote>Google Summer of Code</quote> están en
<filename
class="directory">//depot/projects/soc2005/<replaceable>nombre_del_proyecto</replaceable>/...</filename>
en el servidor &os; de <application>Perforce</application>.</para>
<para>Entre las responsabilidades del mentor del proyecto
está seleccionar un nombre adecuado para dicho proyecto y
hacer que el estudiante sea capaz de trabajar con
<application>Perforce</application>.</para>
<para>El acceso al servidor &os; de
<application>Perforce</application> no implica pasar a ser miembro
de la comunidad de committers del CVS de &os;, aunque animamos
de todo corazón a todos los estudiantes que consideren la
posibilidad de unirse al proyecto cuando estén listos
para ello.</para>
</sect1>
</article>