ext2_dealloc_inode(), clarifies dealloc vs delete
[akaros.git] / Documentation / glibc.txt
1 glibc.txt:
2 Barret Rhoden
3 Last updated: 2010-08-22
4 ----------------------------------------------
5 This document is an attempt to gather knowledge about how to work with the
6 glibc port.  This is based on my half-assed struggling with the port done by
7 kevin and andrew.
8
9 When to recompile (other than when changing libc)
10 --------------------------
11 Whenever you change a kernel header (something in kern/include/ros),
12 technically you should rebuild.  It isn't critical in all places, such as for
13 files that aren't included by glibc, or for files that haven't changed
14 something that glibc relies on.
15
16 After any recompile, don't forget to rebuild userspace apps (make userclean,
17 make install-libs) and to refresh your FS.
18
19 How to recompile glibc
20 --------------------------
21 Normally, make x86 (or whatever) works fairly well.  However, sometimes you
22 need to rebuild all of glibc.  This might be on a hunch, or to get rid of
23 things that might have compiled, but are failing to link and don't seem to
24 rebuild.
25
26 In this event, the next step is to remove the build directories
27 (i686-ros-glibc-*) and also the hidden files (.i686-ros-glibc*).  If you get
28 errors from make very early on about not finding some targets (such as
29 install-headers), you forgot to delete the hidden files.
30
31 Then next step up would be to remove the glibc-XXX folder (whatever the
32 version is).  Sometimes you aren't sure if old changes are sitting around in
33 this folder that aren't getting overwritten by the real source of our changes,
34 the -ros folder.  A lovely example of this is an old Makefile for the nss
35 subdir.  It was altered to remove some things, notably the files service,
36 which translates into libnss_files - which is needed by other things (nis,
37 etc).  To fix this, I had to notice an -ros version of the Makefile (after I
38 realized it was the problem), and that the Makefile was being included - it
39 was just faulty.
40
41 Finally, you can always make clean, but the overall XCC Makefile will clean
42 everything - including gcc and binutils.
43
44 Note that if you are making a trivial addition to a kernel header, you can get
45 away with just copying it to its location in the XCC install directory
46 (sys-include).
47
48 The -ros folder
49 --------------------------
50 All changes to glibc must be made in the glibc-XXX-ros folder.  Any changes
51 here will be copied over to the real glibc folder when it is made.  If you
52 want to remove a file that was originally in the -ros folder, you need to
53 manually remove it from the glibc-XXX folder as well.  The updating scripts
54 will not remove a file.
55
56 The sysdeps folder
57 --------------------------
58 Most of your changes will go here.  Every system that has a glibc port should
59 have one of these folders, with its system-specific ports.  The files here are
60 normally files expected elsewhere in libc, and the glibc build system knows to
61 look in these places.
62
63 Simply dropping a file in here will not get it built.  It will for many files,
64 but some others that weren't expected will need to be manually added to a
65 Makefile.  If you notice some files not getting compiled, (drop a #error in
66 there), you'll need to add it to a Makefile.  In the main sysdeps/Makefile,
67 add the filename (minus .c) to the sysdeps var.  Look at sa_len for an
68 example.  Sometimes you'll need to be careful about adding it for some
69 subdirectories and not others (you probably only want to add a C file for one
70 subdir).  Check out Linux's port for help.
71
72 Sometimes you have files that you want to change outside of the sysdeps
73 folder.  These still go in the glibc-XXX-ros folder, but not in sysdeps.  The
74 main example we have right now is features.h.  At one point, I wanted to
75 change sys/socket.h.  Simply adding it to sysdeps/ros/sys/socket.h would not
76 change the main sys/socket.h, nor would the sysdep version get included first.
77 Putting it in the -ros/sys/ folder did it (though ultimately I didn't want the
78 change).  The point is, sysdeps doesn't mirror and override the main tree for
79 all files - it is behind some others in the search/include path.
80
81 Subdirs
82 --------------------------
83 As a note, these 'subdirectories' are the "primary folders" (i.e. addons),
84 such as inet, ncsd, libio, whatever.  These are the root folders in glibc,
85 representing some major functionality.  They can be built with the
86 --enable-addons switch, which by default builds all of them.  Sort of!
87
88 To really get them to even be available for a port, you need to "include" them
89 in a certain manner.  There are two ways.  One is the Subdirs file in the
90 sysdeps/ros/ directory.  Putting a subdir name in here means glibc will try to
91 build it; it is available to be an addon.  Careful with these, since a lot of
92 the folders tend to need each other (like most all of the ones in unix/inet).
93
94 If you want a massive subsystem, such as "unix/inet" or "posix", you can add
95 it to the sysdeps/ros/Implies file.  You will get a bunch of these folders at
96 once, plus some other unspecified stuff (necessary for the overall system,
97 perhaps?).  If you add "unix/inet", you get more than just its Subdirs.
98
99 Also note that these subdirs can depend on each other, noted in the "Depends"
100 file.  Presumably this will cause them to get made...
101
102 Unimplemented Stubs
103 --------------------------
104 There are a lot of things we haven't ported, but we have the stub functions so
105 that we can at least compile things against it.  When you compile (including
106 regular programs), you'll get warnings about this.  
107
108 Linux ASM bits
109 --------------------------
110 We've included some header files from Linux's kernel.  For now, we just need
111 something to keep glibc happy, even though ROS doesn't have any networking
112 syscalls.  Don't rely on this stuff too much.  These files, and other future
113 glibc compatibility kernel headers, are in kern/include/ros/glibc-asm.
114
115 Tips, Questions, and Misc Notes
116 --------------------------
117 - Grep and find are your friend.
118 - Watch what Linux does.
119 - The kernel headers end up getting installed to the sys-include/ directory,
120   while the regular glib headers go to the include directory.
121 - atomic_swap might have issues (warnings about signedness differences)
122 - It's not always clear which files in the -ros folder actually need to be
123   there (presumably they all do), and in what manner they were modified and
124   from which original copy.  Ideally, the ROS-specific changes to large files
125   will be commented.
126 - the SHARED flag is a bit of a mess - things get compiled differently for
127   shared vs static, and it can get complicated with start.c, tls.c, etc.
128 - What things in one file rely heavily on another file?  Are there non-obvious
129   gotchas?  (yes, and no one documented them).
130
131 Ghetto Things (Feel free to fix them):
132 --------------------------
133 - ptsname: we needed to have the sysdep (was being looked for by the login
134   subdir make process), but having the actual functions in it caused a link
135   error (multiple declarations).  So we have an empty file...