Difference between pages "UEFI Install Guide" and "Zope HOWTO"

(Difference between pages)
m
 
m (Updated some of the syntax on the page.)
 
Line 1: Line 1:
This tutorial will show you how to install Funtoo on a UEFI system. UEFI, also known as the [[Wikipedia:Unified Extensible Firmware Interface|Unified Extensible Firmware Interface]], is a new firmware interface that is used on some newer computers as a replacement for the traditional PC BIOS. It has an integrated boot loader, so setting up booting is different.
+
This page documents how to use Zope with Funtoo Experimental, which currently has good Zope support thanks to [[Progress Overlay Python]] integration.
  
This tutorial is meant to be an "overlay" over the Regular Funtoo Installation. Follow the normal installation and only follow steps in this tutorial when dealing with partitioning and configuring the boot loader (GRUB). All steps are otherwise identical to the regular installation process.
+
== About Zope ==
  
== What Are We Doing? ==
+
Zope is an Open Source application server framework written in Python. It has an interesting history which you should familiarize yourself with before starting Zope development, as it contains several interesting twists and turns.
  
This guide will show you how to set up your UEFI system to load the GRUB boot loader, which will then load your Funtoo Linux kernel and initramfs. This is the "UEFI + GRUB" method as described on the [[Boot Methods]] page.
+
=== Zope History ===
  
== First Steps ==
+
{{Note|This HOWTO targets Zope 2.13, which includes Five. It is typically the version you should be using for new Zope projects.}}
  
To install Funtoo Linux on a UEFI system, first you need to boot SysRescueCD in UEFI mode. To do this, enable UEFI in your BIOS, and if necessary disable legacy booting. After some fiddling, you should be able to boot SysRescueCD and get a black and white text menu instead of the traditional aqua/cyan-colored menu. The black and white menu indicates that you booted SysRescueCD in UEFI mode. Once you've accomplished this, you're ready to continue with your Funtoo Linux installation and partition your drive. See below for details.
+
* There are two versions of Zope: Zope 2 and Zope 3. One might assume that Zope 3 is the version that people should use for new software development projects by default, but this is not the case. Most Zope-based projects continue to use Zope 2. Zope 3 was an attempt to redesign Zope 2 from scratch, and is completely different from Zope 2, but it was not adopted by the community.
  
{{fancynote|If the <tt>/sys/firmware/efi</tt> directory exists, then you have successfully booted in EFI mode and will be able to configure your Funtoo system to boot in EFI mode. If the directory doesn't exist, fix this first. It is a requirement for setting up EFI booting.}}
+
* There is also something called [http://codespeak.net/z3/five/ Five] (named because it is "2 + 3") that backports many of the new features of Zope 3 into the Zope 2 framework. Several projects will use Zope 2 plus Five in order to use some of the newer features in Zope. Five was merged into mainline Zope 2 in early 2010, and first appeared in Zope 2.8.
  
== Partitioning ==
+
* You can learn more about the history of Zope 2, 3 and Five in the [http://svn.zope.org/Zope/trunk/src/Products/Five/README.txt?view=markup Five README].
  
To set up your partitions for UEFI booting, you will create a ~500MB FAT32 partition on <tt>/dev/sda1</tt>, and set it to type <tt>EF00</tt> using <tt>gdisk</tt>.  
+
* To make things even more interesting, work on [http://docs.zope.org/zope2/releases/4.0/ Zope 4] is underway, and it will be based on 2.13 rather than 3.x. It includes a number of [http://docs.zope.org/zope2/releases/4.0/CHANGES.html#restructuring incompatible changes] with prior versions.
 +
=== Zope Resources ===
  
<console>
+
Now that you understand what version of Zope you should be targeting (2.13), we can point you towards the correct documentation :)
Command: ##i##n ↵
+
Partition Number: ##i##1 ↵
+
First sector: ##i##↵
+
Last sector: ##i##+500M ↵
+
Hex Code: ##i##EF00
+
</console>
+
  
This partition will serve as your Funtoo <tt>/boot</tt> filesystem as well as the partition that the UEFI firmware can read to load GRUB. Then you will set up swap on <tt>/dev/sda2</tt> and your root filesystem on <tt>/dev/sda3</tt>. To create the FAT32 filesystem, type:
+
; '''[http://docs.zope.org/zope2/zope2book/ The Zope 2 Book]'''
 +
: This book provides a general introduction to Zope concepts and ZMI. It is a good place to start, but doesn't provide a direct introduction to Zope development. It's recommended that you skim through this book to familiarize yourself with Zope. It generally does not assume much prior knowledge about Web development or Python.
 +
; '''[http://docs.zope.org/zope2/zdgbook/ Zope Developer's Guide]'''
 +
: This guide will give you a better introduction to Zope development. It assumes you already know Python. Skip chapters 1 and 2 and start in [http://docs.zope.org/zope2/zdgbook/ComponentsAndInterfaces.html chapter 3], which covers components and interfaces. [http://docs.zope.org/zope2/zdgbook/Products.html Chapter 5] covers the creation of your first product.
 +
; '''[http://codespeak.net/z3/five/manual.html The Five Manual]'''
 +
: We're not done yet. There is a bunch of stuff in Zope 2.13 that is not in the official documentation. Namely, the stuff in Five.
 +
; '''[http://docs.zope.org/ztkpackages.html ZTK Documentation]'''
 +
: ZTK 
 +
; '''ZCA'''
 +
: [http://www.muthukadan.net/docs/zca.html A Comprehensive Guide to Zope Component Architecture] offers a good introduction to the programming concepts of ZCA. We also have a new page on [[Zope Component Architecture]] which will help you to understand the big picture of ZCA and why it is useful. ZCML ("Z-camel") is a part of ZCA and  was introduced in Zope 3, so typically you will find ZCML documented within Zope 3 documentation and book.
 +
; '''Content Components'''
 +
: Views and Viewlets: [http://docs.zope.org/zope.viewlet/index.html This tutorial on viewlets] also contains some viewlet-related ZCML examples near the end. The "Content Component way" of developing in Zope seems to be a Zope 3 thing and tied to ZCML. Chapter 13+ of Stephan Richter's ''Zope 3 Developer's Handbook'' (book) seems to cover this quite well. You will probably also want to check out Philipp Weitershausen's ''Web Component Development with Zope 3'' (book).
 +
; '''[http://wiki.zope.org/zope2/Zope2Wiki Zope 2 Wiki]'''
 +
: Main wiki page for all things related to Zope 2.
 +
; '''[http://docs.zope.org docs.zope.org]'''
 +
: This is the main site for Zope documentation.
  
<console>
+
== First Steps ==
# ##i##mkfs.vfat -F 32 /dev/sda1
+
</console>
+
  
Your <tt>/etc/fstab</tt> entry for this filesystem will also differ, and will look like this:
+
First, you will need to emerge {{Package|net-zope/zope}}:
 +
{{console|body=
 +
###i## emerge zope
 +
}}
 +
Zope is now installed.
  
<pre>
+
== Project Skeleton ==
/dev/sda1 /boot vfat noatime 1 2
+
</pre>
+
  
== Kernel ==
+
{{Note|Zope should be run by a regular user account, not as the root user.}}
  
=== VFAT ===
+
The first step in using Zope is to ensure that you are using a regular user account. As a regular user, create a new directory called {{c|zope_test}}:
 
+
{{console|body=
Make sure you add VFAT support to your kernel if you are building it manually.
+
$##bl## cd
 
+
$##bl## mkdir zope_test
=== EFI Framebuffer ===
+
 
+
If you have the following option enabled in your kernel, then uvesafb and efifb will not be able to detect the framebuffer:
+
 
+
{{kernelop|title=Bus options (PCI etc.)|desc=
+
    [*] Mark VGA/VBE/EFI FB as generic system framebuffer (NEW)
+
 
}}
 
}}
 
+
Now, enter the directory, and create an "instance", which is a set of files and directories that are used to contain a Zope project:
If you have that option enabled, ''you must also enable'':
+
{{console|body=
 
+
$##bl## cd zope_test
{{kernelop|title=Device Drivers,Graphics support,Frame buffer Devices|desc=
+
$##bl## /usr/lib/zope-2.13/bin/mkzopeinstance
    [*]  Simple framebuffer support
+
 
}}
 
}}
 +
You will see the following output and will be prompted to answer a few questions:
 +
{{console|body=
 +
Please choose a directory in which you'd like to install
 +
Zope "instance home" files such as database files, configuration
 +
files, etc.
  
This is the preferred method of using the EFI framebuffer, the efifb and uvesafb drivers will be used as a fallback if the above is not compatible.
+
Directory: instance
 +
Please choose a username and password for the initial user.
 +
These will be the credentials you use to initially manage
 +
your new Zope instance.
  
== Boot Loader ==
+
Username: admin
=== EFI Stub method ===
+
Password: ****
Instead of bothering with the installation of GRUB, you can consider using the UEFI firmware of your computer to boot your kernel.
+
Verify password: ****  
 
+
==== Kernel Configuration ====
+
To prepare your kernel to boot with EFI stub, make sure that the following options are built in to your kernel:
+
{{kernelop|title=Processor type and features|desc=
+
[*] EFI runtime service support
+
[*]    EFI stub support
+
[ ]        EFI mixed-mode support
+
 
+
[*] Built-in kernel command line
+
(kernel options that you want to pass go here)
+
 
}}
 
}}
{{note|Commands that you would normally pass, such as, <code>video{{=}}uvesafb:1920x1080-32,mtrr:3,ywrap</code>, should be put here. In other words, anything that you would normally add to <code>/etc/boot.conf</code> after <code>params +{{=}}</code> should be added to the built-in kernel command line as well.}}
+
Now, we will start our Zope instance:
 +
{{console|body=
 +
$##bl## cd instance
 +
$##bl## bin/runzope
 +
}}
 +
Now that Zope is functional, you can go to the {{c|localhost:8080/manage}} URL in your web browser: you will be prompted to log in. Enter the username and password you specified. You are now logged in to the ZMI (Zope Management Interface.)
  
{{important|You should specifiy the position of your rootfs here. For example: <code>root{{=}}/dev/sdb1</code>.}}
+
You can stop your application by pressing Control-C. In the future, you can start and stop your Zope instance using the following commands:
 
+
{{console|body=
If your system requires an initramfs to boot, do not worry, you can build that in to the kernel. One thing that you should know, however, is that the kernel only takes plaintext and <code>.cpio</code> files for initramfs source files. Therefore, if you use an application to generate an initramfs for you, make sure that it does not use gzip compression. To build better-initramfs-bin without gzip compression, disable the gzip use flag for the package:
+
$##bl## zopectl start
{{file|name=/etc/portage/package.usr|desc= |body=
+
$##bl## zopectl stop
sys-kernel/better-initramfs-bin -gzip
+
}}
+
then emerge better-initramfs:
+
<console>
+
###i## emerge better-initramfs-bin
+
</console>
+
If you check in your <code>/boot</code> directory, you should see a file called <code>initramfs.cpio</code>. See below to include this file in your kernel.
+
{{kernelop|title=General setup|desc=
+
[*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
+
(/path/to/initramfs/file.cpio)
+
For better-initramfs-bin:
+
(/boot/initramfs.cpio)
+
 
}}
 
}}
 +
{{Note|{{c|zopectl start}} will cause your instance to run in the background rather than consuming a shell console.}}
  
==== Building and installing the kernel ====
+
== First Project ==
After you have configured your kernel, build it, install it to <code>/boot</code>, and then create a copy of the image to store in the EFI boot directory:
+
<console>
+
###i## pwd
+
/usr/src/linux
+
###i## make -jn
+
###i## make -jn install modules_install
+
###i## mkdir -vp /boot/EFI/Boot
+
###i## cp -v /boot/vmlinuz-x.x.x /boot/EFI/Boot/bootx64.efi
+
</console>
+
When you have finished all of this, you should be able to reboot and enjoy yor new Funtoo system!
+
  
=== Grub method ===
+
We will create a single, very primitive Zope package, consisting of an Interface for a TODO class, and a TODO class.
==== Emerging GRUB ====
+
  
You will still use GRUB as a boot loader, but before emerging grub, you will need to enable EFI booting. To do this,
+
Create the following files and directories relative to your project root:
add the following line to <tt>/etc/portage/make.conf</tt>:
+
  
<pre>
+
* Create the directory {{c|lib/python/example}}.
GRUB_PLATFORMS="efi-64"
+
* Create the file {{c|lib/python/example/__init__.py}} by typing {{c|touch lib/python/example/__init__.py}}.
</pre>
+
* Create these files:
  
Then, <tt>emerge grub</tt>. You will notice <tt>efibootmgr</tt> getting pulled in as a dependency. This is expected and good.
+
=== {{c|example-configure.zcml}} ===
  
==== Installing GRUB ====
+
This file registers the {{c|example}} directory you created in {{c|lib/python}} as a ''package'', so that it is seen by Zope. Edit {{c|/etc/package-includes/example-configure.zcml}}:
 +
{{file|name=/etc/package-includes/example-configure.zcml|body=
 +
<include package="example" />
 +
}}
  
Now, for the magic of getting everything in place for booting. You should copy your kernel and initramfs (if you have one -- you will if you are following the default install) to <tt>/boot</tt>. GRUB will boot those. But how do we get UEFI to boot GRUB? Well, we need to run the following command:
+
=== {{c|interfaces.py}} ===
  
<console>
+
The following file defines the <tt>ITODO</tt> interface, and also uses some Zope Schema functions to define what kind of data we expect to store in objects that implement <tt>ITODO</tt>. Edit <code>/lib/python/example/interfaces.py</code> with your favorite text editor:
# ##i##grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda
+
</console>
+
This command will simply install all the stuff to <tt>/boot/EFI</tt> and <tt>/boot/grub</tt> that your system needs to boot. In particular, the <tt>/boot/EFI/grub/grubx64.efi</tt> file will be created. This is the GRUB boot image that UEFI will load and start.
+
  
A more detailed explanation of the flags used in the above command:
+
<syntaxhighlight lang="python">
* <code>--target=x86_64-efi</code>: Tells GRUB that we want to install it in a way that allows it to boot in UEFI
+
from zope.interface import Interface
* <code>--efi-directory=/boot</code>: All GRUB UEFI files will be installed in ''/boot''
+
from zope.schema import List, Text, TextLine, Int
* <code>--bootloader-id="Funtoo Linux [GRUB]"</code>: This flag is not necessary for GRUB to boot. However, it allows you to change the text of the boot option in the UEFI BIOS. The stuff in the quotes can be set to anything that you would like.
+
* <code>--recheck</code>: If a device map already exists on the disk or partition that GRUB is being installed on, it will be removed.
+
* <code>/dev/sda</code>:The device that we are installing GRUB on.
+
  
==== Configuring GRUB ====
+
class ITODO(Interface):
 +
    name = TextLine(title=u'Name', required=True)
 +
    todo = List(title=u"TODO Items", required=True, value_type=TextLine(title=u'TODO'))
 +
    daysleft = Int(title=u'Days left to complete', required=True)
 +
    description = Text(title=u'Description', required=True)
 +
</syntaxhighlight>
  
OK, now UEFI has the GRUB image it needs to boot. But we still need to configure GRUB itself so it finds and boots your kernel and initramfs. This is done by performing the following steps. Since boot-update doesn't yet support UEFI, we will use boot-update, but then edit our <code>/boot/grub/grub.cfg</code> to support UEFI booting.  
+
=== {{c|TODO.py}} ===
  
First, you will need to edit <code>/etc/boot.conf</code>. Format this as you would if you were booting without UEFI. If you are not sure how this should look, below is an example of what it could look like if you are booting from an unencrypted ext4 partition:
+
Now, we define {{c|TODO}} to be a ''persistent'' object, meaning it can be stored in the ZODB. We specify that it implements our previously-defined {{c|ITODO}} interface, and provide reasonable defaults for all values when we create a new TODO object. Edit {{c|/lib/python/example/TODO.py}} using your favorite text editor:
 +
{{file|name=/lib/python/example/TODO.py|lang=python|body=
 +
from persistent import Persistent
 +
from zope.interface import implements
 +
from example.interfaces import ITODO
  
{{file|name=/etc/boot.conf|desc=|body=
+
class TODO(Persistent):
boot {
+
    implements(ITODO)
        generate grub
+
    name = u''
        default "Funtoo Linux"
+
    todo = []
        timeout 3
+
    daysleft = 0
}
+
    description = u''
 
+
"Funtoo Linux" {
+
        kernel vmlinuz[-v]
+
        params += rootfstype=ext4 root=/dev/sda2
+
}
+
 
}}
 
}}
  
After you have edited your <code>/etc/boot.conf</code> file, run <code>boot-update</code>. If you check your <code>/boot/grub/grub.cfg</code> now, you should see something like this:
+
=== {{c|configure.zcml}} ===
  
{{file|name=/boot/grub/grub.cfg|desc=|body=
+
Create the <tt>/lib/python/example/configure.zcml</tt> configuration file:
set timeout=3
+
<syntaxhighlight lang="xml">
 +
<configure xmlns="http://namespaces.zope.org/zope"
 +
    xmlns:five="http://namespaces.zope.org/five"
 +
    xmlns:browser="http://namespaces.zope.org/browser">
 +
</configure>
 +
</syntaxhighlight>
  
  insmod part_gpt
+
== Debug Mode ==
  insmod fat
+
  set root=(hostdisk//dev/sda,gpt1)
+
  search --no-floppy --fs-uuid --set 3CFD-6884
+
if loadfont /grub/unifont.pf2; then
+
  set gfxmode=text
+
  insmod gfxterm
+
  insmod vbe
+
  terminal_output gfxterm
+
fi
+
  
set menu_color_normal=cyan/blue
+
We can test our first project by entering debug mode:
set menu_color_highlight=blue/cyan
+
<console>
 +
$##i## bin/zopectl debug
 +
Starting debugger (the name "app" is bound to the top-level Zope object)
 +
</console>
  
menuentry "Funtoo Linux - vmlinuz-3.16.3" {
+
Now, let's try creating a new TODO object and writing it out to a ZODB database:
  insmod part_gpt
+
<console>
  insmod fat
+
>>> from ZODB import FileStorage, DB
  set root=(hostdisk//dev/sda,gpt1)
+
>>> storage = FileStorage.FileStorage('mydatabase.fs')
  search --no-floppy --fs-uuid --set 3CFD-6884
+
>>> db = DB(storage)
  linux /vmlinuz-3.16.3 video=uvesafb:1920x1080-32,mtrr:3,ywrap rootfstype=ext4 root=/dev/sda2
+
>>> connection = db.open()
  set gfxpayload=text
+
>>> import transaction
}
+
>>> root = connection.root()
set default=0
+
>>> from example.TODO import TODO
}}
+
>>> a = TODO
 
+
>>> a.name = u'My TODOs'
To get your <code>/boot/grub/grub.cfg</code> to support booting with UEFI, make your <code>/boot/grub/grub.cfg</code> look like this:
+
>>> a.TODOS = [ u'Do Laundry', u'Wash Dishes' ]
{{file|name=/boot/grub/grub.cfg|desc=|body=
+
>>> a.daysleft = 1
set timeout=3
+
>>> a.description = u'Things I need to do today.'
 
+
>>> root[u'today'] = a
  insmod part_gpt
+
>>> transaction.commit()
  insmod fat
+
</console>
  insmod efi_gop
+
  insmod efi_uga
+
  set root=(hostdisk//dev/sda,gpt1)
+
  search --no-floppy --fs-uuid --set 3CFD-6884
+
if loadfont /grub/unifont.pf2; then
+
  set gfxmode=auto
+
  insmod gfxterm
+
  insmod vbe
+
  terminal_output gfxterm
+
fi
+
 
+
set menu_color_normal=cyan/blue
+
set menu_color_highlight=blue/cyan
+
 
+
menuentry "Funtoo Linux - vmlinuz-3.16.3" {
+
  insmod part_gpt
+
  insmod fat
+
  set root=(hostdisk//dev/sda,gpt1)
+
  search --no-floppy --fs-uuid --set 3CFD-6884
+
  linux /vmlinuz-3.16.3 video=uvesafb:1920x1080-32,mtrr:3,ywrap rootfstype=ext4 root=/dev/sda2
+
  set gfxpayload=keep
+
}
+
set default=0
+
}}
+
 
+
The lines that we have added and altered do the following:
+
* <code>insmod efi_gop</code> and <code>insmod efi_uga</code>: Both of these involve adding support for the UEFI framebuffer to GRUB.
+
* <code>set gfxmode=auto</code>: Instead of having the GRUB boot option screen being displayed at the smallest resolution possible, changing this to auto will make it fit the resolution of your display.
+
 
+
== Known Issues ==
+
*With pure UEFI boot mode, with legacy mode disabled, following error expected:
+
** video driver not supported, boot hangs, hard reboot required.
+
*Choose UEFI first, next legacy driver. It depends on motherboard vendor and efi bios version.
+
**In UEFI bios choose grub option, if your succeeded with above guide, additional menu should appear in Boot Menu, otherwise it boots into EFI shell: <code>grub:NAME of you hard drive</code>
+
* On some systems, installing the packages that are required for UEFI booting with any gcc later than a 4.x.x release may lead to a black screen after the GRUB screen. To fix this, before you begin installing any packages on your system, emerge =gcc-4.6.4-r2 and proceed with the installation as usual. Remember to switch your compiler back to the version of gcc that came with your system after you have finished installing. To do this, use <code>gcc-config 2</code>. This problem can also be fixed by following the [[Efi Stub guide]] instead of the GRUB one.
+
 
+
=== Done! ===
+
 
+
Remember to follow all other steps in the regular Funtoo Install Guide. Assuming you did everything correctly, your system should now boot via UEFI! We will be adding UEFI support to boot-update soon to make this process easier.
+
  
 
[[Category:HOWTO]]
 
[[Category:HOWTO]]

Latest revision as of 17:32, June 25, 2015

This page documents how to use Zope with Funtoo Experimental, which currently has good Zope support thanks to Progress Overlay Python integration.

About Zope

Zope is an Open Source application server framework written in Python. It has an interesting history which you should familiarize yourself with before starting Zope development, as it contains several interesting twists and turns.

Zope History

Note

This HOWTO targets Zope 2.13, which includes Five. It is typically the version you should be using for new Zope projects.

  • There are two versions of Zope: Zope 2 and Zope 3. One might assume that Zope 3 is the version that people should use for new software development projects by default, but this is not the case. Most Zope-based projects continue to use Zope 2. Zope 3 was an attempt to redesign Zope 2 from scratch, and is completely different from Zope 2, but it was not adopted by the community.
  • There is also something called Five (named because it is "2 + 3") that backports many of the new features of Zope 3 into the Zope 2 framework. Several projects will use Zope 2 plus Five in order to use some of the newer features in Zope. Five was merged into mainline Zope 2 in early 2010, and first appeared in Zope 2.8.
  • You can learn more about the history of Zope 2, 3 and Five in the Five README.
  • To make things even more interesting, work on Zope 4 is underway, and it will be based on 2.13 rather than 3.x. It includes a number of incompatible changes with prior versions.

Zope Resources

Now that you understand what version of Zope you should be targeting (2.13), we can point you towards the correct documentation :)

The Zope 2 Book
This book provides a general introduction to Zope concepts and ZMI. It is a good place to start, but doesn't provide a direct introduction to Zope development. It's recommended that you skim through this book to familiarize yourself with Zope. It generally does not assume much prior knowledge about Web development or Python.
Zope Developer's Guide
This guide will give you a better introduction to Zope development. It assumes you already know Python. Skip chapters 1 and 2 and start in chapter 3, which covers components and interfaces. Chapter 5 covers the creation of your first product.
The Five Manual
We're not done yet. There is a bunch of stuff in Zope 2.13 that is not in the official documentation. Namely, the stuff in Five.
ZTK Documentation
ZTK
ZCA
A Comprehensive Guide to Zope Component Architecture offers a good introduction to the programming concepts of ZCA. We also have a new page on Zope Component Architecture which will help you to understand the big picture of ZCA and why it is useful. ZCML ("Z-camel") is a part of ZCA and was introduced in Zope 3, so typically you will find ZCML documented within Zope 3 documentation and book.
Content Components
Views and Viewlets: This tutorial on viewlets also contains some viewlet-related ZCML examples near the end. The "Content Component way" of developing in Zope seems to be a Zope 3 thing and tied to ZCML. Chapter 13+ of Stephan Richter's Zope 3 Developer's Handbook (book) seems to cover this quite well. You will probably also want to check out Philipp Weitershausen's Web Component Development with Zope 3 (book).
Zope 2 Wiki
Main wiki page for all things related to Zope 2.
docs.zope.org
This is the main site for Zope documentation.

First Steps

First, you will need to emerge net-zope/zope (package not on wiki - please add):

# emerge zope

Zope is now installed.

Project Skeleton

Note

Zope should be run by a regular user account, not as the root user.

The first step in using Zope is to ensure that you are using a regular user account. As a regular user, create a new directory called zope_test:

$ cd
$ mkdir zope_test

Now, enter the directory, and create an "instance", which is a set of files and directories that are used to contain a Zope project:

$ cd zope_test
$ /usr/lib/zope-2.13/bin/mkzopeinstance

You will see the following output and will be prompted to answer a few questions:

Please choose a directory in which you'd like to install
Zope "instance home" files such as database files, configuration
files, etc.

Directory: instance
Please choose a username and password for the initial user.
These will be the credentials you use to initially manage
your new Zope instance.

Username: admin
Password: ****
Verify password: ****

Now, we will start our Zope instance:

$ cd instance
$ bin/runzope

Now that Zope is functional, you can go to the localhost:8080/manage URL in your web browser: you will be prompted to log in. Enter the username and password you specified. You are now logged in to the ZMI (Zope Management Interface.)

You can stop your application by pressing Control-C. In the future, you can start and stop your Zope instance using the following commands:

$ zopectl start
$ zopectl stop
Note

zopectl start will cause your instance to run in the background rather than consuming a shell console.

First Project

We will create a single, very primitive Zope package, consisting of an Interface for a TODO class, and a TODO class.

Create the following files and directories relative to your project root:

  • Create the directory lib/python/example.
  • Create the file lib/python/example/__init__.py by typing touch lib/python/example/__init__.py.
  • Create these files:

example-configure.zcml

This file registers the example directory you created in lib/python as a package, so that it is seen by Zope. Edit /etc/package-includes/example-configure.zcml:

/etc/package-includes/example-configure.zcml
<include package="example" />

interfaces.py

The following file defines the ITODO interface, and also uses some Zope Schema functions to define what kind of data we expect to store in objects that implement ITODO. Edit /lib/python/example/interfaces.py with your favorite text editor:

from zope.interface import Interface
from zope.schema import List, Text, TextLine, Int
 
class ITODO(Interface):
    name = TextLine(title=u'Name', required=True)
    todo = List(title=u"TODO Items", required=True, value_type=TextLine(title=u'TODO'))
    daysleft = Int(title=u'Days left to complete', required=True)
    description = Text(title=u'Description', required=True)

TODO.py

Now, we define TODO to be a persistent object, meaning it can be stored in the ZODB. We specify that it implements our previously-defined ITODO interface, and provide reasonable defaults for all values when we create a new TODO object. Edit /lib/python/example/TODO.py using your favorite text editor:

/lib/python/example/TODO.py (python source code)
from persistent import Persistent
from zope.interface import implements
from example.interfaces import ITODO
 
class TODO(Persistent):
    implements(ITODO)
    name = u''
    todo = []
    daysleft = 0
    description = u''

configure.zcml

Create the /lib/python/example/configure.zcml configuration file:

<configure xmlns="http://namespaces.zope.org/zope"
     xmlns:five="http://namespaces.zope.org/five"
     xmlns:browser="http://namespaces.zope.org/browser">
</configure>

Debug Mode

We can test our first project by entering debug mode:

$ bin/zopectl debug
Starting debugger (the name "app" is bound to the top-level Zope object)

Now, let's try creating a new TODO object and writing it out to a ZODB database:

>>> from ZODB import FileStorage, DB
>>> storage = FileStorage.FileStorage('mydatabase.fs')
>>> db = DB(storage)
>>> connection = db.open()
>>> import transaction
>>> root = connection.root()
>>> from example.TODO import TODO
>>> a = TODO
>>> a.name = u'My TODOs'
>>> a.TODOS = [ u'Do Laundry', u'Wash Dishes' ]
>>> a.daysleft = 1
>>> a.description = u'Things I need to do today.'
>>> root[u'today'] = a
>>> transaction.commit()