You must configure and build newlib in a directory separate from the source tree. Typically, you make a build directory, cd into it and run:
When you configure you must configure from the top-level of the src directory. You do not configure from newlib's directory. The top-level configure script will eventually configure newlib for you. Since newlib is a target library it actually configures when you make all or make all-target-newlib.
back to topFor cross-compilation info, check out the crosstool-NG project. When setting up a unified source directory, remember that the newlib subdirectory should be a sibling to gcc, binutils, etc.. All of these net projects share a top-level directory so you only want to copy or link the tools/libraries subdirectories specifically. For example, the newlib project when downloaded has a src directory with a number of subdirectories including newlib and libgloss. When gcc is downloaded, it too has a src directory with a gcc subdirectory. To bring in newlib and libgloss, a user could link the newlib and libgloss subdirectories of the newlib source tree into the src tree of gcc.
back to topTo see a list of configuration options specific for newlib, run:
The optspace option allows certain functions to use algorithms designed for space rather than speed. It also compiles the whole library with -Os.
The newlib-mb option allows multibyte support. This multibyte support enables three special locales: "C-JIS", "C-SJIS", and "C-EUCJP". These locales are basically the "C" locale with multibyte-function support for the specified Japanese character sets. The multibyte support extends to the mb and wc functions in stdlib as well as format characters for the printf and scanf family of routines.
The newlib-hw-fp option causes the library to use a set of math routines that use floating-point algorithms. By default, the newlib library math routines use integer-based algorithms to perform the desired functionality. For a platform that has fast floating-point support, the floating-point algorithms may be faster and smaller.
back to topNewlib, by default, builds "multilibs". What this term means is that multiple versions of newlib are built according to a set of permutated options determined by the compiler. For example, for a chip that can be set to either run in big-endian or little-endian mode, the compiler would designate target libraries be built with each endianness. In the case where there are multiple features, the compiler will designate libraries be built with permutations of the various options so as to cover all possible combinations.
When built, the compiler sets up a list of option permutations and a set of directory names to place multilibs in. This information is exposed externally via the "print-multi-lib" option which outputs the list in a compact form. When the compiler is called to compile and link an application, it recognizes multilib-designated options and knows which versions of target libraries, such as newlib, to link with which has been built with the same options. For this to work, you want gcc and newlib installed in the same directory. You also want to link using the compiler rather than linking objects via "ld". The ld linker does not accept compiler options and thus does not know how to map to the correct target libraries. If you decide to use ld instead of gcc to link, you will be forced to specify the location of newlib manually.
When newlib is building, it simply invokes the compiler with the -print-multi-lib option to get the set of multilibs it should create. Try xxx-yyy-gcc -print-multi-lib to see the list of permutations that will be used for your platform to build newlib.
For more information about how to interpret the output of -print-multi-lib, see the gcc documentation. For problems relating to which multilibs are selected and which are missing, contact the gcc list.
back to topA basic port needs to alter a number of files and add some directories.
In this directory you need to have a setjmp/longjmp implementation. This is required because setjmp/longjmp usually is assembler. Look at the libc/machine/fr30 directory and copy/modify the files in there.
This defines the ieee endianness for your platform. The compiler should be defining something that identifies your machine. In some cases, the endianness may be a compiler-option so you may have to check another define in addition to your platform identifier. See examples in the file.
You need to specify the setjmp buffer characteristics to match up with your setjmp/longjmp implementation. This is just the size of the setjmp buffer. See file for examples.
This has various defines as needed. Mostly, it defines some max values. There are defaults that may apply to your platform in which case you needn't do anything.
You need to add your configuration so newlib can recognize it. You should specify your new machine directory for your platform via the machine_dir variable. If needed, you can add special newlib compile flags. The sys_dir is for OS stuff so you won't need to alter that. Older platforms used the sys_dir to implement syscalls but this is not correct and is a historical nuisance. The syscall_dir is a choice, but I recommend as a default to specify syscall_dir=syscalls. Read the comments in newlib/libc/include/reent.h for an explanation of choices.
You need to add a bsp for your platform. This is the minimum set of syscalls needed by newlib and any linker scripts needed. This varies from board to board (it can also be a simulator). See the mn10300 or fr30 for examples. You will need to edit configure.in and regenerate configure so it will build your new files. By default you get libnosys which gives you a set of default syscall stubs. The majority of the stubs just return failure. You still need to supply an __exit routine. This can be as simple as generating an exception to stop the program.
If you need to override any default machine header files, you can
add a machine directory to newlib/libc/machine/
This assumes you have already handled adding your new configuration to the top directory files.
Now linux is a different animal. It is an OS that has an extensive set of syscalls. If you look in the newlib/libc/sys/linux directory, you will find a number of syscalls there (e.g. see io.c). There is a set of basic syscall macros that are defined for the particular platform. For the x86, you will find these macros defined in newlib/libc/sys/linux/machine/i386/syscall.h file. At the moment, linux support is only for x86. To add another platform, the syscall.h file would have to be supplied for the new platform plus some other platform-specific files would need to be ported as well.
back to topWhenever the configure.ac, acinclude.m4, Makefile.am, or Makefile.inc files are modified, you should use the autoreconf program to regenerate everything. This command should be run in the top-level newlib directory.
Note how we do not specify any specific files or directories. This is because it will walk all subdirectories and update all the files as needed.
Generated files such as aclocal.m4, configure, or Makefile.in should never be modified directly.
Newlib doesn't attempt to be bleeding-edge when it comes to autotool usage. Each snapshot release will be made using a set of autotools felt to be stable. You can determine the versions that were used by looking at the generated files (each documents what level was used). For example, to see the level of autoconf, look inside the configure script you wish to regenerate. To see the level of automake, look inside a Makefile.in file. Using the same version of the tool as was used previously is usually recommended, but you may have more recent tools installed on your system. If you do not have commit rights, you should omit submitting generated files and allow a committer to regenerate them for you. In some cases, committers may start using newer versions of autotools for various changes as we approach the date of a snapshot.
Newlib currently has a yearly snapshot which is taken in December. The snapshot is taken from the source code repository and tar'd. The tar file is made available here through the newlib web-site: https://sourceware.org/newlib. Newlib does not have a formal test cycle so a snapshot is not necessarily more stable than the current repository contents. Testing does occur as a number of consumers of newlib such as Cygwin and RTEMS do extra testing as time draws nearer to a snapshot. In general, one is advised to try using the source repository as it contains the latest fixes. No fixes are posted to snapshot releases.
The libm/mathfp directory was a failed experiment to implement the libm library using floating-point algorithms. The idea was to make this optional for platforms that had floating-point instructions. Some of the algorithms use recursion and are simply inaccurate, especially when presented the full range of possible input arguments such as very large and very small values. The library used to be enabled via the --enable-newlib-hw-fp option, but has been disabled in configure.in as of Oct 24/2012.