Empaquetar tu Actividad

Agregar setup.py

Siempre debes agregar el programa en Python llamado setup.py en el mismo directorio donde está el programa con tu Actividad. Todo setup.py es exactamente igual a otro setup.py cualquiera. La copia que está en nuestro repositorio Git se ve así:

#!/usr/bin/env python
# Copyright (C) 2006, Red Hat, Inc.
#
# This program is free software; you can redistribute it
# and/or modify it under the terms of the GNU General
# Public License as published by the Free Software
# Foundation; either version 2 of the License, or (at
# your option) any later version.
#
# This program is distributed in the hope that it will
# be useful, but WITHOUT ANY WARRANTY; without even
# the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE.  See the GNU General
# Public License for more details.
#
# You should have received a copy of the GNU General
# Public License along with this program; if not,
# write to the Free Software Foundation, Inc.,
# 51 Franklin St, Fifth Floor, Boston, MA
# 02110-1301  USA
from sugar.activity import bundlebuilder
bundlebuilder.start()

Asegúrate de copiar el texto íntegro que ves aquí encima, incluidos los comentarios.

Sugar usa al programa setup.py para diversos fines. Si ejecutas setup.py por línea de comandos verás las opciones que te propone y entenderás que hacen.

[jim@simmons bookexamples]$ ./setup.py
/usr/lib/python2.6/site-packages/sugar/util.py:25:
DeprecationWarning: the sha module is deprecated;
use the hashlib module instead
  import sha
Available commands:
build                Build generated files
dev                  Setup for development
dist_xo              Create a xo bundle package
dist_source          Create a tar source package
fix_manifest         Add missing files to the manifest
genpot               Generate the gettext pot file
install              Install the activity in the system
(Type "./setup.py <command> --help" for help about a
particular command's options.
NT:
build                Build(construir) genera archivos
dev                  Setup para development-desarrollo
dist_xo              Crea un paquete bundle xo
dist_source          Crea un paquete fuente tar
fix_manifest         Agrega los archivos que faltan en el manifest
genpot               Genera el archivo gettext pot
install              Instala la actividad en el sistema

Estaremos ejecutando alguno de estos comandos más tarde. No se preocupen por la advertencia DeprecationWarning. Este es un mensaje de Python para avisar que existe un procedimiento nuevo, que mejora el que estamos usando, pero el modo anterior siempre funciona. Es un error que viene del código mismo de Sugar y que será corregido en alguna versión posterior.

Crear activity.info

Ahora crearemos un directorio en el mismo lugar donde esté nuestro programa (.py) y lo llamaremos activity. Dentro de ese directorio vamos crear el archivo llamado activity.info y a escribir en él las líneas que vemos aquí abajo. En este ejemplo vemos las líneas correspondientes a mi primer Actividad.

[Activity]
name = Read ETexts II
service_name = net.flossmanuals.ReadEtextsActivity
icon = read-etexts
exec = sugar-activity ReadEtextsActivity.ReadEtextsActivity
show_launcher = no
activity_version = 1
mime_types = text/plain;application/zip
license = GPLv2+

Este archivo es el que dice a Sugar como ejecutar cada Actividad. Las propiedades requeridas para este archivo son:

name	Es el nombre de tu Actividad tal y como lo verá el usuario.
service_name	Es el nombre único con el que Sugar referirá a tu Actividad. Toda entrada al Journal que tu Actividad registre tendrá este nombre en su metadata, de modo que cuando alguien retome la entrada en el Journal, Sugar sabrá que programa creó la entrada y lo usará para abrirla.
icon	Es el nombre del ícono que creaste para tu Actividad. Como los íconos son siempre archivos .svg , el nombre del archivo en el ejemplo es simplemente read-etexts.svg.
exec	Esto informa a Sugar como lanzar tu Actividad.Le dice que cree una instancia de la clase ReadEtextsActivity que encontrará en ReadEtextsActivity.py
show_launcher	Hay dos formas comunes para lanzar una Actividad, cliquear sobre el ícono en la vista de Actividades o retomar la Actividad desde el Journal. No tiene sentido añadir un ícono al anillo de Actividades para una Actividad como la de este ejemplo. Ésta sólo puede ser retomada desde el Journal.
activity_version	Un entero que representa el número de versión de tu programa. La primer versión será 1, la siguiente 2 y de así en más.
mime_types	Generalmente al retomar una entrada del Diario, este lanza la Actividad que la creó. En el caso de entradas que no están creadas por una Actividad, como en e-books, es necesario indicar de otra forma al Diario cual Actividad utilizar. Un tipo MIME es el nombre de un tipo corriente de archivo, por ejemplo text/plain (texto plano) , text/html, application/zip y application/pdf. Con esta entrada estamos indicando al Diario que tipos maneja nuestro programa, en este ejemplo textos planos o empaquetados zip.
license	Ser dueño de una computadora no es como tener un automóvil. El dueño de un automóvil puede comercializarlo como quiera. Puede venderlo, alquilarlo, destruirlo o lo que sea. Con un programa de una computadora siempre existe una licencia que indica a la persona lo que está permitido hacer. La GPLv2+ es el estándar popular de licencias que puede ser usada para Actividades, y como este es mi programa, elijo GPLv2. Cuando estés pronto para comenzar a distribuir tus Actividades trendré más que decir sobre licencias.

Crear un ícono

Necesitamos crear un ícono llamado read-etexts.svg y guardarlo en el subdirectorio activity. Usaremos Inkscape para crear el ícono. Con el menú New (Nuevo) en Inkscape seleccionamos icon_48×48. Esto nos dará un área con buenas medidas para dibujar.

No hay que ser un experto para crear el ícono. De hecho, cuanto más simple sea el ícono mejor. Al dibujar el ícono recuerda el siguiente punteo:

Tu ícono debe verse bien en muy distintos rangos de tamaño, desde muy muy chico a grande.
Tiene que ser reconocible cuando es muy muy chico.
Solo puedes usar dos colores uno para el trazo (stroke) y otro para el color de relleno (fill). No importa cuales elijas porque Sugar necesita reemplazar tus opciones, así que te conviene usar trazos negros y fondo blanco.
Un color de relleno sólo aplica en un área donde el borde esté cerrado. Si dibujas una caja y uno de las esquinas queda abierta esta no podrá llenarse con color. Dibujar a mano alzada es sólo para talentosos. Circunferencias, rectángulos y arcos son sencillos de dibujar en Inkscape así que úsalos cuando puedas.
Inkscape también dibuja cajas 3D usando dos puntos perspectivos. No los usen. Los íconos deben ser imágenes planas. El 3D luce mal en un ícono.
Es realmente difícil tener una idea buena para el ícono Una vez me entusiasmé con una linda imagen de un mueble fichero para tarjetas de cartón como ícono para Get Internet Archive Books. Pero claro, nadie de menos de cuarenta años ha visto un fichero así y muy pocos entenderían entonces mi simbología.

Cuando termines de hacer tu ícono deberás modificarlo para que Sugar trabaje con él. Especialmente se debe explicitar que Sugar puede usar su propia pareja de colores para el trazo (stroke) y el relleno (fill). SVG es un formato basado en XML, que es sólo un texto con algunas etiquetas especiales. Esto significa que al terminar de editar la imagen en Inkscape la podemos cargar en Eric y editarla como archivo de texto.

No voy a poner el archivo SVG entero en este capítulo porque la mayor parte queda intacta, no hay que hacerle nada. La parte que debes modificar está casi al principio.

Antes:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg

Después:

<?xml version="1.0" ?>
<!DOCTYPE svg  PUBLIC '-//W3C//DTD SVG 1.1//EN'
  'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd' [
        <!ENTITY stroke_color "#000000">
        <!ENTITY fill_color "#FFFFFF">
]><svg

Ahora, en el cuerpo del documento habrán varias referencias a fill y a stroke como parte de un atributo llamado style. Cada línea o forma que dibujes tendrá un texto como este:

<rect
   style="fill:#ffffff;stroke:#000000;stroke-opacity:1"
   id="rect904"
   width="36.142857"
   height="32.142857"
   x="4.1428571"
   y="7.1428571" />

Deberás cambiar cada uno de esos textos para que se vean como este otro:

<rect
   style="fill:&fill_color;;stroke:&stroke_color;
;stroke-opacity:1"
   id="rect904"
   width="36.142857"
   height="32.142857"
   x="4.1428571"
   y="7.1428571" />

Importante. Notar que &stroke_color; y &fill_color; terminan ambas con punto-y-coma (;), y a la vez, punto-y-coma se usa para separar las propiedades de style. Esta es la causa de un error de principiante muy común que es quitar el punto-y-coma de separación porque dos punto-y-comas seguidos no se ven bien. No duden, ambos punto-y-comas (semicolons) en el mismo renglón son intencionales e indispensables. También, notarás que el valor para style debe estar todo en una sola línea. Acá -en el libro- lo partimos para que calzara en la diagramación de la hoja, no hagas esto en el archivo de tu ícono.

Armar el archivo MANIFEST

Recordemos que setup.py tiene una opción para actualizar el manifiesto. Hagamos la prueba:

./setup.py fix_manifest
/usr/lib/python2.6/site-packages/sugar/util.py:25:
DeprecationWarning: the sha module is deprecated;
use the hashlib module instead
  import sha
WARNING:root:Missing po/ dir, cannot build_locale
WARNING:root:Activity directory lacks a MANIFEST file.

Efectivamente, esto construye un archivo MANIFEST conteniendo todo lo que esté en el directorio y en subdirectorios. El directorio /po por el que protesta, es el directorio que se usa para traducir la Actividad a distintos idiomas. Podemos ignorarlo por el momento.

El archivo creado tendrá algún contenido extra, del que podemos librarnos usando Eric. El archivo corregido deberá verse simplemente así:

setup.py
ReadEtextsActivity.py
activity/read-etexts.svg
activity/activity.info

Instalar la Actividad

Solamente nos falta una cosa antes de poder probar nuestra Actividad en un emulador de Sugar. Nos falta instalarla. En este caso instalarla quiere decir crear un vínculo simbólico entre el directorio ~/Activities/ y nuestro código. El símbolo ~ refiere siempre al directorio "hogar" del usuario bajo el que estemos corriendo Sugar y un vínculo simbólico es sólo una forma de hacer que un archivo o carpeta parezca estar en más de un lugar sin haberlo copiado. Crearemos este vínculo simbólico (symbolic link) usando nuevamente setup.py:

./setup.py dev

Ejecutar nuestra Actividad

Finalmente podemos ejecutar nuestra Actividad en Sugar. Para esto es necesario saber usar un emulador de Sugar.

Fedora no proporciona una opción de menú para la creación del emulador, pero es fácil agregarlo directamente. El comando a escribir es sencillo:

sugar-emulator

Si tu resolución de pantalla fuera menor que la resolución que el emulador Sugar usa por defecto, éste se verá en modo pantalla completa. Esto no es conveniente para el testeo así que deberás especificar tu propia resolución:

sugar-emulator -i 800x600

Señalemos que esta opción está disponible sólo en Fedora 11 y posteriores.

Cuando ejecutas el emulador se despliega una ventana y el entorno Sugar arranca adentro de ella. Se ve algo así:

Al ejecutar el emulador puede pasar que algunas teclas no funcionen bien. Esto se debe a errores (bugs) en el software Xephyr que es quien crea la ventana donde corre Sugar. A veces es difícil identificar la distribución del teclado y algunas teclas se interpretan mal. Mis experiencias son con Fedora 11, las teclas de función no me anduvieron y para las flechas tuve que usar el teclado numérico. Logré recomponer las teclas de función incluyendo esta línea en ~/.sugar/debug:

run setxkbmap <keymap name>

Esto necesita explicación adicional. Primero, el símbolo "~" refiere al directorio hogar. Segundo, cualquier archivo que en Linux comience con un punto será un archivo oculto, por lo tanto para verlo debemos usar la opción de mostrar archivos ocultos en el navegador de archivos de GNOME. Finalmente en el <keymap name> es un código de país con dos caracteres: us para Estados Unidos, fr para Francia, de para Alemania, etc.

Para probar esta Actividad vamos a necesitar tener un libro en el Journal, así que usaremos la Actividad Browse (Navegar) para visitar por ejemplo el Proyecto Gutenberg y descargar un libro a nuestro gusto. Lo importante es descargarlo en formato Zip porque Browse no puede descargar texto plano al Journal. Browse descarga el zip y lo abre como si fuera un sitio web para verlo. El archivo zip aparecerá como descargado en el Diario.

No vamos a poder abrir el archivo desde el Diario con doble clic porque nuestra programa no creó la entrada y hay muchas Actividades que soportan el tipo MIME zip. Para abrirlo necesitamos usar la opción Start with (empezar con) del menú de opciones como se ve acá:

Esto es lo que vemos cuando abrimos la entrada del Diario.

Técnicamente esta es la primer iteración de nuestra Actividad. Iteración es una palabra muy utilizada que básicamente refiere a cosas que se hacen más de una vez. En este libro hemos construido una Actividad haciendo un paso a la vez para mostrar los conceptos básicos para escribir Actividades, pero escribir un programa en partes, testearlas, obtener feedback y entonces seguir escribiendo es una forma muy productiva de crear software (al usar la palabra iteración el asunto suena bastante más formal de como es de verdad).

Aunque tu Actividad ya sea lo suficientemente buena como para que se la muestres a tu familia y amigos, debemos mejorarla antes un poco más para publicarla por ahí. Cómo refinar tu Actividad es lo que veremos a continuación.

Traducido Ana Cichero, Uruguay^{^}

your comment:

name :
comment :