Advice from former students that may be helpful for SummerOfCode:
About the Wiki
It is powered by Moinmoin. It has a markup language to format the pages, which seems to be a bit complicated at first. When you edit your page the GUI editor might be useful, but personally, I don't really like it, I think it is very inconvenient. You can check other wiki pages to find out the markup. The most important elements are:
== Heading == === Smaller Heading === * Bulleting list item 1 * Bulleting list item 2 * Bulleting list item 3 ''Italic text'' '''Bold text''' ||Table header1||Table header2||...|| ||Table item||Table item||...||
Choose a user name in the following format: JohnDoe, WilliamSmith, ... Such formed words are automatically transformed to links. On http://wiki.freebsd.org/SummerOfCode2013 your name should be presented as this kind of wiki name so that one can click and read your proposal and personal introduction if you want to include such. I don't think there would be anything else to say about the wiki.
I like it a lot, in some aspects it is easier to use than CVS. So there is a big repo on the server. With CVS you normally only check out the sources on demand. With Perforce you will have a local working copy. The entity which covers the settings of your working copy is called a client. In this terminology it does not refer to the fact that you will connect to the reporitory in the rule of a client, it refers to the collection of you setting. Accordingly, on a single computer you can have more clients to various Perforce servers or to the same server with various layouts. A command line argument or an environment variable will determine which client is used. A client is identified with its name. The name is normally built up by two components: your username and your host. The two is divided by an underscore. Examples: gabor_pluto, jim_whatever
So, let's see how to set up your environment when you have your account. First, install devel/p4. Now, set the following environment variables according to your shell:
P4PORT=perforce.freebsd.org:1666 P4USER=yourusername P4CLIENT=yourusername_yourhost P4PASSWD=yourpassword P4DIFF=/usr/bin/diff
The last line needs some explication. Perforce has a bit different diff format then patch(1) and diff(1). If you set this environment variable, you will get an output that is compatible with patch(1) when you generate a diff with Perforce.
Now you need to set up your client. Run p4 client. The first 6 fields are obvious. Root will be the root directory of your working copy. Options are okay as are, SubmitOptions as well. LineEnd will determine the line ending (Win/Mac/UNIX), if you are developing from FreeBSD then local is fine. View is the most important part. You will only need small parts of the huge Perforce repo, so you will tell Perforce here which are those. An example:
The first part is the source path from the repository and the second one is the local destination. Note that gabor_server is my client name. It will be substituted with the specified root path, which is /home/gabor/perforce for me, thus it will resolve to /home/gabor/perforce/projects/soc2008/gabor_textproc. The 3 points tell Perforce to fetch all of the files and subdirectories from the specified directory. Obviously when you set up your account firtstly, you won't have a //depot/projects/soc2008/yourusername_yourproject/... directory in the repository yet. Just set it up in this way and create the local directory. You can put files there and add them with p4 add if you don't want to make a branch from the FreeBSD source tree. When you added your files with p4 add, you can make the changes take effect with p4 submit, which will open your default editor to edit the log for your applied changes. Later if you want to edit a file that is already added, you need to open it for edit: p4 edit filename. You can delete files with p4 remove.
About Perforce Branches
The best functionality of Perforce is that it can handle branches very well. A directory can be a branch and everything goes very fast, this is the reason that Perforce is used for experimental code. The method is the following. The CVS tree is exported to Perforce regularly to //depot/vendor/freebsd/. In the Perforce repository you can select location and make a branch from it to another one. Let's see an example. I want to work on the bsdlabel utility, which is located in src/sbin/bsdlabel, thus I'll find it in Perforce in //depot/vendor/freebsd/src/sbin/bsdlabel/. My working directory is //depot/projects/soc2008/gabor_bsdlabel. I need to set up an assigment from the source to the destination. This entity is called branch in Perforce. A branch is identified by a name in a form like username_branchname, like gabor_bsdlabel. Let's create this branch: p4 branch gabor_bsdlabel. Your editor will show up. The first 4 fields are obvious and now you might have a feeling about what View is. You need to put to assignment there, in our example: //depot/vendor/freebsd/src/sbin/bsdlabel/... //depot/projects/soc2008/gabor_bsdlabel/... Save it and you're ready. Now you need to do an integration: p4 integrate -b gabor_bsdlabel Perforce will map the original files to your selected destination. Submit your changes so that they take effect: p4 submit. Now you can work on your branch and if you want to merge the changes from CVS run the integrate command in the very same way and it will lok for changes. If there are changes, you need to resolve them. I normally do it in 3 steps:
p4 resolve -as p4 resolve -am p4 resolve
The first one safely resolves the files which only contain changes either in the vendor branch or in your branch. The second one safely merges the files which contain changes in both branches. The third one interactively lets you handle the conflicts. After you have resolved the conflicts, submit your changes.
A Perforce tip
If you delete one file from the submit log, it will not be be submitted - this allows you to easily submit subsets of changed files without having to list each file you wish to submit manually on the command line.
http://planet.freebsdish.org is a blog aggregator for FreeBSD related activities. Summer of Code students are welcome to blog about their progress, as well. Ask Florent Thoumie (flz@) about the details if interested.
Some Useful Links
We're mostly on Efnet. The wiki lists the available channels. The most important ones are:
#freebsd-soc (recommended for all FreeBSD SoC students) #bsdcode #bsdports #bsddocs
I think the names will tell you which one to choose for your purpose.
Other Advice and Tips
Send your suggestions for this page to firstname.lastname@example.org.