Difference between pages "The Gentoo.org Redesign, Part 1" and "Repository Configuration"

(Difference between pages)
(Created page with "{{Article |Subtitle=A site reborn |Summary=Have you ever woken up one morning and suddenly realized that your cute little personal development Web site isn't really that great...")
 
(Undo revision 9202 by Duncan.britton (talk))
 
Line 1: Line 1:
{{Article
+
{{Warning|This article is a work-in-progress referring to a future Portage version. It does not apply to the current Funtoo Portage version. Please do not update your configuration yet.}}
|Subtitle=A site reborn
+
|Summary=Have you ever woken up one morning and suddenly realized that your cute little personal development Web site isn't really that great? If so, you're in good company. In this series, Daniel Robbins shares his experiences as he redesigns the www.gentoo.org Web site using technologies like XML, XSLT, and Python. Along the way, you may find some excellent approaches to use for your next Web site redesign. In this article, Daniel creates a user-centric action plan and introduces pytext, an embedded Python interpreter.
+
|Author=Drobbins
+
}}
+
==  An unruly horde ==
+
  
Fellow software developer, may I ask you a question? Why is it that although many of us are intimately familiar with Web technologies such as HTML, CGI, Perl, Python, Java technology, and XML, our very own Web sites -- the ones devoted to our precious development projects -- look like they were thrown together by an unruly horde of hyperactive 12-year-olds? Why, oh why, is this so?
+
Starting with Portage-2.3.8, a switch to a new repository configuration framework is complete and users may want to update their configuration files. This document aims to describe the goals for the new framework and how to use it.
  
Could it be because most of the time, we've left our Web site out to rot while we squander our precious time hacking away on our free software projects? The answer, at least in my case, is a most definite "Yes."
+
== Multiple repository layout ==
 +
One of the most important changes is the switch from the old ''overlay'' layout to a new cleaner ''repository'' system. The new layout is more flexible and more predictable. For example, repositories can now use resources (eclasses, for example) provided by other repositories.
  
When I'm not writing articles for IBM developerWorks or being a new dad, I'm feverishly working on the next release of Gentoo Linux, along with my skilled team of volunteers. And, yes, Gentoo Linux has its own Web site (see Resources). As of right now (March 2001), our Web site isn't that special; that's because we don't spend much time working on it because we're generally engrossed in improving Gentoo Linux itself. Sure, our site does have several admittedly cute logos that I whipped up using Xara X (see Resources), but when you look past the eye candy, our site leaves a lot to be desired. Maybe yours does too. If so, I have one thing to say to you -- welcome to the club.
+
The old layout was based on the concept of one ''main tree'' and optionally a number of overlays. The main tree provided base system ebuilds, eclasses, profiles, while overlays mostly were able to provide their own ebuilds. The ebuild provided by overlays overrode the ebuilds in main tree to the extend of making it impossible to install the main tree version. Overlays could also provide eclasses for their own ebuilds and package.* entries that applied to all overlays and to the main tree. The Package Manager is responsible for updating the main tree, while overlays are managed externally.
  
==  www.gentoo.org ==
+
The new layout is based on the concept of one or more configurable repositories. Each repository can either be stand-alone or depend upon other repositories. The distribution provides a repository called ''funtoo'' (a drop-in replacement for Gentoo's ''gentoo'' repository). Users can install more repositories at they will, the repositories providing their own ebuilds, eclasses and profiles as necessary and/or using them from other repositories. Users can explicitly choose the repository they want to install packages from. The Package Manager can update all repositories.
  
In our case, our Web site dilemma exists because our project has been growing, and our Web site hasn't. Now that Gentoo Linux is approaching the 1.0 release (when it'll be officially ready for non-developers) and is growing in popularity, we need to start seriously looking at how our Web site can better serve its users. Here's a snapshot of www.gentoo.org:
+
== Portage configuration ==
 +
=== New repository layout ===
 +
The repository configuration should be stored in <code>/etc/portage/repos.conf</code>. It can be either a single file or a directory containing one or more ''.conf'' files.
  
<div style="margin: 10px;">[[File:L-redesign-01.gif|frame|class=img-responsive|The current (March 2001) state of affairs at www.gentoo.org]]</div>
+
The default configuration is installed as <code>/usr/share/portage/config/repos.conf</code>. This file is internal configuration file installed with portage ebuild and should '''not''' be modified. Instead, the configuration in <code>/etc/portage/repos.conf</code> can override the defaults specified there.
  
As you can see, we have all the bare essentials -- a description of Gentoo Linux, a features list, a daily Changelog (automatically updated thanks to Python), and a bunch of important links (to the download sites, to our mailing list sign-up pages, and to cvsWeb). We also have links to three documentation resources -- the Gentoo Linux Install Guide and Development Guides, and Christian Zander's NVIDIA Troubleshooting Guide.
+
The configuration uses format similar to Windows .ini files. Each section heading (repository name in square brackets) signifies a single repository, followed by one or more key-value option pairs. For example, the following file copies default configuration for Funtoo repository:
  
However, while the site seems O.K., we're missing a lot of things. The most obvious is documentation -- our installation and development guides need a lot of work. And then we need to add an FAQ, new links, new user information...the list is endless.
+
{{file|name=/etc/portage/repos.conf/funtoo.conf|desc=Example configuration override for Funtoo repository to move it to non-standard location|body=
 +
[funtoo]
 +
# moved to non-standard location!
 +
location = /var/db/repos/funtoo
 +
sync-type = git
 +
sync-uri = git://github.com/funtoo/ports-2015.git
 +
auto-sync = yes
 +
}}
  
== Content vs. display ==
+
The most useful repository configuration options are listed below:
 +
;location: ''Obligatory.'' Specifies the directory where repository is/will be stored. If Portage knows how to sync the repository and the location does not exist, it will be created on next ''emerge --sync''. Otherwise, the directory must exist.
 +
;priority: Specifies the priority used for ordering ebuilds from different repositories. If two repositories provide an ebuild with matching versions, the repository with higher priority will be used.
 +
;auto-sync: Specifies whether ''emerge --sync'' should update the repository. Defaults to ''yes'' if ''sync-type'' is specified, ''no'' otherwise.
 +
;sync-depth: Specifies ''--depth'' for git clone. Used only on initial sync. Defaults to 1. Can be set to 0 to force full clone (not pass ''--depth'' at all).
 +
;sync-type: Specifies syncing/update method. Can be one of: ''cvs'', ''git'', ''rsync'', ''svn''.
 +
;sync-umask: Specifies the umask used when updating/syncing the repository.
 +
;sync-uri: Specifies remote URI from which the repository will be cloned/synced. Can use any syntax valid for a particular syncing method.
 +
;sync-user: Specifies the user[:group] used to update/sync the repository. If ''FEATURES=usersync'' is used, defaults to the credentials of directory owner.
  
And now we come to our second problem. Right now, all of our work is done in raw HTML; I hack away at the index.html file until it looks O.K. Even worse, our Web documentation is written in raw HTML. This isn't a good thing from a development perspective because our raw content (consisting of paragraphs, sections, chapters) is garbled together with a bunch of display-related HTML tags. This, of course, makes it difficult to change both the content and the look of our site. While this approach has worked so far, it is bound to cause problems as our site continues to grow.
+
Additionally a <code>[DEFAULT]</code> section may be specified. Options in this section are used as defaults for all repositories.
  
Clearly, we need to be using better technologies behind the scenes. Instead of using HTML directly, we need to start using things like XML, XSLT, and Python. The goal is to automate as much as possible so that we can add and expand our site with ease. If we do our job well, even major future changes to our site should be relatively painless.
+
=== Migrating existing configurations ===
 +
The new configuration format provides replacement for existing configuration done through <code>/etc/portage/make.conf</code> and environment variables. While the variables are still supported for backwards compatibility, users are recommended to move to the new configuration scheme. Funtoo portage ebuild is planned to  make the migration unattended (repos.conf installed automatically to ease the config steps) with the following file:
 +
 +
{{file|name=/etc/portage/repos.conf/funtoo.conf|body=
 +
[funtoo]
 +
location = /usr/portage
 +
sync-type = git
 +
sync-uri = git://github.com/funtoo/ports-2015.git
 +
auto-sync = yes
 +
}}
 +
The following replacements are provided for existing variables:
 +
;PORTDIR: Used to specify main tree location. Replaced by ''location'' key in the section corresponding to the default repository (<code>[funtoo]</code> by default).
 +
;PORTDIR_OVERLAY: Used to specify locations of overlays. Each of the paths needs to be replaced with a separate repository section, with the path placed in ''location'' key. Additionally, ''priority'' may be used to force specific ordering of ebuild overrides.
 +
;SYNC: Used to specify URI for syncing the main repository, also implied a protocol for doing that. Replaced by the ''sync-uri'' and ''sync-type'' keys in the default repository section.
 +
;SYNC_UMASK: Used to specify umask for syncing repositories. Replaced by ''sync-umask'' key in repository configuration. Can be specified in <code>[DEFAULT]</code> section to apply to all repositories.
 +
;SYNC_USER: Used to specify user credentials for syncing repositories. Replaced by ''sync-user'' key in repository configuration. Can be specified in <code>[DEFAULT]</code> section to apply to all repositories.
  
== A strategy! ==
+
{{file|name=/etc/portage/make.conf|desc=Example old make.conf file|body=
 +
# user changed PORTDIR location
 +
PORTDIR="/var/db/repos/funtoo"
 +
PORTDIR_OVERLAY="/var/db/repos/foo /var/db/repos/bar"
  
It was clear that we had a lot of work ahead of us. In fact, there was so much to be done that I didn't know where to begin. Just as I was trying to sort out everything in my head, I came across Laura Wonnacott's "Site Savvy" InfoWorld column (see Resources). In it, she explained the concept of "user-centric" design -- how to improve a Web site while keeping the needs of your target audience (in this case, Gentoo Linux users and developers) in focus. Reading the article and taking a look at the "Handbook of User-Centered Design" link from the article helped me to formulate a strategy -- an action plan -- for the redesign:
+
SYNC="git://github.com/funtoo/ports-2015.git"
 +
SYNC_USER="oleg"
 +
SYNC_UMASK="022"
 +
}}
  
# First, clearly define the official goal of the Web site -- in writing. What's it there for, and what's it supposed to do?
+
{{file|name=/etc/portage/repos.conf|desc=Replacement repos.conf file|body=
#  Identify the different categories of users who will be using your site -- your target audience. Rank them in order of priority: Which ones are most important to you?
+
[DEFAULT]
# Set up a system for getting feedback from your target audience, so they can let you know what you're doing right and wrong.
+
sync-user = oleg
# Evaluate the feedback, and use it to determine what parts of the site need to be improved or redesigned. Tackle high-priority sections first.
+
sync-umask = 022
# Once you've selected the part of the site to improve, get to work! During your implementation, make sure that the content and design of the new section caters specifically to the needs of your target audience and fixes all known deficiencies.
+
# When the section redesign is complete, add it to your live site, even if it has a look that's markedly different from your current site. This way, your users can begin benefitting from the newly redesigned section immediately. If there's a problem with the redesign, you'll get user feedback more quickly. Finally, making incremental improvements to your site (rather than revamping the whole site and then rolling it out all at once -- surprise!) will help prevent your users from feeling alienated by your (possibly dramatic) site changes.
+
#  After completing step 6, jump to step 4 and repeat.
+
  
== The mission statement ==
+
[funtoo]
 +
location = /var/db/repos/funtoo
 +
sync-type = git
 +
sync-uri = git://github.com/funtoo/ports-2015.git
  
I was happy to discover that we already had step 3 in place. We had received several e-mail suggestions from visitors to the site, and our developer mailing list also served as a way of exchanging suggestions and comments. However, I had never really completed steps 1 or 2. While the answers may seem obvious, I did find it helpful to actually sit down and write out our mission statement:
+
[foo]
 +
location = /var/db/repos/foo
 +
priority = 1
  
www.gentoo.org exists to assist those who use and develop for Gentoo Linux by providing relevant, up-to-date information about Gentoo Linux and Linux in general, focusing on topics related to Gentoo Linux installation, use, administration, and development. As the central hub for all things Gentoo, the site should also feature important news relevant to Gentoo Linux users and developers. In addition to catering to Gentoo Linux users and developers, www.gentoo.org has the secondary purpose of meeting the needs of potential Gentoo Linux users, providing the information they need to decide whether Gentoo Linux is right for them.
+
[bar]
 +
location = /var/db/repos/bar
 +
priority = 2
 +
}}
  
== The target audience ==
+
The <code>repos.conf</code> configuration can be further extended with ''sync-type'' and ''sync-uri'' for overlays to get ''emerge --sync'' updating them automatically.
  
So far, so good. Now for step 2 -- defining our target audience:
+
let's see a real example of tree and overlays added.  
 +
{{file|name=/etc/portage/repos.conf|desc=Replacement repos.conf file|body=
  
www.gentoo.org has three target audiences -- Gentoo Linux developers, users, and potential users. While no one group is absolutely a higher priority than another, right now the needs of Gentoo Linux developers are our highest priority, followed by Gentoo Linux users, and then potential users. This is because Gentoo Linux is currently in a prerelease state. When Gentoo Linux reaches version 1.0, Gentoo Linux users and potential users will also become a priority.
+
[gentoo]
 
+
location = /usr/portage
== Comments and suggestions ==
+
sync-type = git
 
+
sync-uri = git://github.com/funtoo/ports-2012.git
O.K., now it's time to evaluate the suggestions and comments we've collected:
+
 
+
[funtoo-overlay]
Over the past few months, we've received a number of suggestions from Web site visitors. Overwhelmingly, people are requesting better documentation -- for both developers and users. Several developers have asked if we could create a mailing list that would be devoted exclusively to describing CVS commits.
+
location = /root/git/funtoo-overlay
 
+
Interestingly, we've also received a couple of e-mails asking whether Gentoo Linux is a commercial or free product. I'm guessing that because our main logo is inscribed with the name "Gentoo Technologies, Inc." (our legal corporation name), people assume that we have a commercial focus. Modifying our logo so that it reads "Gentoo Linux" and adding small opening paragraph to the main page explaining that we are a free software project should help.
+
[funtoo-gnome]
 
+
location = /root/git/funtoo-gnome-overlay
== The improvement list ==
+
 
+
O.K., now let's turn these suggestions into a list of possible improvements:
+
 
+
* Revamp main page
+
** Implementation: update logo and add free software blurb
+
** Goal: to clearly state that we are a free software project
+
** Target group: potential users
+
**  Difficulty: medium
+
* Improve basic user documentation
+
**  Implementation: new XML/XSLT system, verbose documentation
+
** Goal: to make it easier for users to install Gentoo Linux
+
** Target group: new users
+
** Difficulty: medium
+
*Improve/create developer documentation
+
** Implementation: new XML/XSLT system, CVS guide, dev guide, Portage guide
+
**  Goal: to help our developers to do a great job
+
** Target group: developers
+
** Difficulty: hard
+
*Add a CVS mailing list
+
** Implementation: use our existing mailman mailing list manager
+
** Goal: to better inform our developers
+
** Target group: developers
+
** Difficulty: easy
+
 
+
== A selection! ==
+
 
+
Two things leap out from the list, for different reasons. The first is the CVS mailing list -- this one is a no-brainer because it's so easy to implement. Often, it makes sense to implement the easiest changes first so that users can benefit from them right away.
+
 
+
The second big thing that leaps out from the list is the need for developer documentation. This is a longer-term project that will require much more work. From my conversations with the other developers, we all appear to be in agreement that some kind of XML/XSL approach is the right solution.
+
 
+
== The XML/XSL prototype ==
+
 
+
To help start the process, I developed a prototype XML syntax to be used for all our online documentation. By using this XML syntax (called "guide"), our documentation will be clearly organized into paragraphs, sections, and chapters (using XML tags like <section>, <chapter>, etc.) while remaining free of any display-related tags. To create the HTML for display on our site, I created a prototype set of XSL transforms. By using an XSLT processor such as Sablotron, our guide XML files can be converted into HTML as follows:
+
 
+
devguide.xml + guide.xsl ---XSLT processor---> devguide.html
+
 
+
The great thing about this XML/XSLT approach is that it separates our raw content (XML) from the display-related information contained in the guide.xsl (XSLT) file. If we ever need to update the look of our Web pages, we simply modify the guide.xsl file and run all our XML through the XSLT processor (Sablotron), creating updated HTML pages. Or, if we need to add a few chapters to the development guide, we can modify devguide.xml. Once we're done, we then run the XML through Sablotron, which then spits out a fully-formatted devguide.html file with several added chapters. Think of XML as the content and XSLT as the display-related formatting macros.
+
 
+
While our entire team is convinced that XML/XSLT is the way to go, we haven't yet agreed upon an official XML syntax. Achim, our development lead, suggested that we use docbook instead of rolling our own XML syntax. However, the prototype guide XML format has helped to start the decision-making process. Because we developers are going to be the ones using the XML/XSL on a daily basis, it's important to choose a solution that we're comfortable with and meets all of our needs. By my next article, I should have a working XML/XSL doc system to show off to you.
+
 
+
== Technology demo: pytext ==
+
 
+
For the most part, our current Web site isn't using any new or super-cool technologies that are worth mentioning. However, there's one notable exception -- our tiny pytext embedded Python interpreter.
+
 
+
Like many of you, I'm a huge Python fan and much prefer it over other scripting languages, so when it came time to add some dynamic content to our Web site, I naturally wanted to use Python. And, as you probably know, when coding dynamic HTML content, it's usually much more convenient to embed the language commands inside the HTML, rather than the other way around. Thus, the need for an embedded Python interpreter that can take a document like this:
+
 
+
<pre>
+
<p>
+
Yeah, sure; I got some questions:<br>
+
<!--code
+
names=["bob","jimmy","ralph"]
+
items=["socks","lunch","accordion"]
+
for x in items:
+
for y in names:
+
print "Anyone seen",y+"'s",x+"?<br>"
+
-->
+
See, told you so.
+
</pre>
+
 
+
....and transform it into this:
+
 
+
<pre>
+
<p>
+
Yeah, sure; I got some questions:<br>
+
Anyone seen bob's socks?<br>
+
Anyone seen jimmy's socks?<br>
+
Anyone seen ralph's socks?<br>
+
Anyone seen bob's lunch?<br>
+
Anyone seen jimmy's lunch?<br>
+
Anyone seen ralph's lunch?<br>
+
Anyone seen bob's accordion?<br>
+
Anyone seen jimmy's accordion?<br>
+
Anyone seen ralph's accordion?<br>
+
See, told you so.
+
</pre>
+
 
+
Here's the source code for pytext:
+
 
+
Code Listing 2.4:
+
{{file|name=pytext|lang=python|desc=The pytext embedded Python interpreter|body=
+
#!/usr/bin/env python2
+
 
+
# pytext 2.1
+
# Copyright 1999-2001 Daniel Robbins
+
# Distributed under the GPL
+
 
+
import sys
+
 
+
def runfile(myarg):
+
  "interprets a text file with embedded elements"
+
  mylocals={}
+
  try:
+
      a=open(myarg,'r')
+
  except IOError:
+
      sys.stderr.write("!!! Error opening "+myarg+"!\n")
+
      return
+
  mylines=a.readlines()
+
  a.close()
+
  pos=0
+
  while pos<len(mylines):
+
      if mylines[pos][0:8]=="<!--code":
+
  mycode=""
+
  pos=pos+1
+
  while (pos<len(mylines)) and (mylines[pos][0:3]!="-->"):
+
      mycode=mycode+mylines[pos]
+
      pos=pos+1
+
  exec(mycode,globals(),mylocals)
+
      else:
+
  sys.stdout.write(mylines[pos])
+
      pos=pos+1
+
 
+
if len(sys.argv)>1:
+
  for x in sys.argv[1:]:
+
      runfile(x)
+
  sys.exit(0)
+
else:
+
  sys.stderr.write
+
    ("pytext 2.1 -- Copyright 1999-2001 Daniel Robbins. ")
+
  sys.stderr.write
+
    ("Distributed under the\nGNU Public License\n\n")
+
  sys.stderr.write
+
    ("Usage: "+sys.argv[0]+" file0 [file1]...\n")
+
  sys.exit(1)
+
 
}}
 
}}
 
+
funtoo-overlay and funtoo-gnome-overlay are an overlays added on top of regular portage tree.
== How pytext works ==
+
[[Category:Portage]]
 
+
Here's how it works. It scans each input line, and most of the time, each input line is simply echoed to stdout. However, if pytext encounters a line beginning with <!--code, then the contents of every line up to the first line beginning with --> are appended to a string called mycode. Pytext then executes the mycode string using the built-in exec() function, effectively creating an embedded Python interpreter.
+
 
+
There's something really beautiful about this particular implementation -- we call exec() in such a way that all modifications to the global and local namespaces are saved. This makes it possible to import a module or define a variable in one embedded block, and then access this previously-created object in a later block, as this example clearly demonstrates:
+
 
+
<pre>
+
<!--code
+
import os
+
foo=23
+
-->
+
 
+
Hello
+
 
+
<!--code
+
print foo
+
if os.path.exists("/tmp/mytmpfile"):
+
print "it exists"
+
else:
+
print "I don't see it"
+
-->
+
</pre>
+
 
+
Handy, eh? pytext serves is an excellent demonstration of the power of Python, and is an extremely useful tool for Python fans. For our current site, we call pytext from a cron job, using it to periodically generate the HTML code for our main page Changelog:
+
 
+
<console>
+
$ ##i##pytext index.ehtml > index.html
+
</console>
+
 
+
That's it for now; I'll see you next time when we'll take a look at the first stage of the www.gentoo.org redesign!
+
{{ArticleFooter}}
+

Revision as of 04:52, February 27, 2015

Warning

This article is a work-in-progress referring to a future Portage version. It does not apply to the current Funtoo Portage version. Please do not update your configuration yet.

Starting with Portage-2.3.8, a switch to a new repository configuration framework is complete and users may want to update their configuration files. This document aims to describe the goals for the new framework and how to use it.

Multiple repository layout

One of the most important changes is the switch from the old overlay layout to a new cleaner repository system. The new layout is more flexible and more predictable. For example, repositories can now use resources (eclasses, for example) provided by other repositories.

The old layout was based on the concept of one main tree and optionally a number of overlays. The main tree provided base system ebuilds, eclasses, profiles, while overlays mostly were able to provide their own ebuilds. The ebuild provided by overlays overrode the ebuilds in main tree to the extend of making it impossible to install the main tree version. Overlays could also provide eclasses for their own ebuilds and package.* entries that applied to all overlays and to the main tree. The Package Manager is responsible for updating the main tree, while overlays are managed externally.

The new layout is based on the concept of one or more configurable repositories. Each repository can either be stand-alone or depend upon other repositories. The distribution provides a repository called funtoo (a drop-in replacement for Gentoo's gentoo repository). Users can install more repositories at they will, the repositories providing their own ebuilds, eclasses and profiles as necessary and/or using them from other repositories. Users can explicitly choose the repository they want to install packages from. The Package Manager can update all repositories.

Portage configuration

New repository layout

The repository configuration should be stored in /etc/portage/repos.conf. It can be either a single file or a directory containing one or more .conf files.

The default configuration is installed as /usr/share/portage/config/repos.conf. This file is internal configuration file installed with portage ebuild and should not be modified. Instead, the configuration in /etc/portage/repos.conf can override the defaults specified there.

The configuration uses format similar to Windows .ini files. Each section heading (repository name in square brackets) signifies a single repository, followed by one or more key-value option pairs. For example, the following file copies default configuration for Funtoo repository:

/etc/portage/repos.conf/funtoo.conf - Example configuration override for Funtoo repository to move it to non-standard location
[funtoo]
# moved to non-standard location!
location = /var/db/repos/funtoo
sync-type = git
sync-uri = git://github.com/funtoo/ports-2015.git
auto-sync = yes

The most useful repository configuration options are listed below:

location
Obligatory. Specifies the directory where repository is/will be stored. If Portage knows how to sync the repository and the location does not exist, it will be created on next emerge --sync. Otherwise, the directory must exist.
priority
Specifies the priority used for ordering ebuilds from different repositories. If two repositories provide an ebuild with matching versions, the repository with higher priority will be used.
auto-sync
Specifies whether emerge --sync should update the repository. Defaults to yes if sync-type is specified, no otherwise.
sync-depth
Specifies --depth for git clone. Used only on initial sync. Defaults to 1. Can be set to 0 to force full clone (not pass --depth at all).
sync-type
Specifies syncing/update method. Can be one of: cvs, git, rsync, svn.
sync-umask
Specifies the umask used when updating/syncing the repository.
sync-uri
Specifies remote URI from which the repository will be cloned/synced. Can use any syntax valid for a particular syncing method.
sync-user
Specifies the user[:group] used to update/sync the repository. If FEATURES=usersync is used, defaults to the credentials of directory owner.

Additionally a [DEFAULT] section may be specified. Options in this section are used as defaults for all repositories.

Migrating existing configurations

The new configuration format provides replacement for existing configuration done through /etc/portage/make.conf and environment variables. While the variables are still supported for backwards compatibility, users are recommended to move to the new configuration scheme. Funtoo portage ebuild is planned to make the migration unattended (repos.conf installed automatically to ease the config steps) with the following file:

/etc/portage/repos.conf/funtoo.conf
[funtoo]
location = /usr/portage
sync-type = git
sync-uri = git://github.com/funtoo/ports-2015.git
auto-sync = yes

The following replacements are provided for existing variables:

PORTDIR
Used to specify main tree location. Replaced by location key in the section corresponding to the default repository ([funtoo] by default).
PORTDIR_OVERLAY
Used to specify locations of overlays. Each of the paths needs to be replaced with a separate repository section, with the path placed in location key. Additionally, priority may be used to force specific ordering of ebuild overrides.
SYNC
Used to specify URI for syncing the main repository, also implied a protocol for doing that. Replaced by the sync-uri and sync-type keys in the default repository section.
SYNC_UMASK
Used to specify umask for syncing repositories. Replaced by sync-umask key in repository configuration. Can be specified in [DEFAULT] section to apply to all repositories.
SYNC_USER
Used to specify user credentials for syncing repositories. Replaced by sync-user key in repository configuration. Can be specified in [DEFAULT] section to apply to all repositories.
/etc/portage/make.conf - Example old make.conf file
# user changed PORTDIR location
PORTDIR="/var/db/repos/funtoo"
PORTDIR_OVERLAY="/var/db/repos/foo /var/db/repos/bar"

SYNC="git://github.com/funtoo/ports-2015.git"
SYNC_USER="oleg"
SYNC_UMASK="022"
/etc/portage/repos.conf - Replacement repos.conf file
[DEFAULT]
sync-user = oleg
sync-umask = 022

[funtoo]
location = /var/db/repos/funtoo
sync-type = git
sync-uri = git://github.com/funtoo/ports-2015.git

[foo]
location = /var/db/repos/foo
priority = 1

[bar]
location = /var/db/repos/bar
priority = 2

The repos.conf configuration can be further extended with sync-type and sync-uri for overlays to get emerge --sync updating them automatically.

let's see a real example of tree and overlays added.

/etc/portage/repos.conf - Replacement repos.conf file
[gentoo]
location = /usr/portage
sync-type = git
sync-uri = git://github.com/funtoo/ports-2012.git
 
[funtoo-overlay]
location = /root/git/funtoo-overlay
 
[funtoo-gnome]
location = /root/git/funtoo-gnome-overlay

funtoo-overlay and funtoo-gnome-overlay are an overlays added on top of regular portage tree.